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THINGS TO KNOW 

develop^ The Apple Technical 
Journal f a quarterly publication of 
Apple Computer's Developer Press 
groups is published in March^ June, 
September^ and December develop 
articles and code have been reviewed 
for robustness by Apple engineers. 

This issue's CD, Subscription issues 
of develop are accompanied by the 
develop Bookmark CD, This CD contains 
a subset of the materials on the monthly 
Developer CD Series, available through 
the Apple Developer Catalog. Included 
on the CD arc this issue and all back 
issues of develop along with the code 
that the articles describe, (The code is 
updated periodically, so always use the 
most recent CD.) The CD also 
contains Technical Notes, sample code, 
and other documentation and tools 
(these contents are subject to change). 
Items referred to as being on ''this 
issuers CD" are located on eitlier the 
Bookmark CD or the Reference 
Library or Tool Chest edition of the 
Developer CD Series, Much of the CD 
contents, including the develop issues 
and code, are also available in the 
Developer Services area on AppleLink 
and at ftp .info, apple,com* See also the 
World Wide Web site for Apple 
Developer Services and Products, at 
h ttp r//de V. i n fo. app I e *com, 

Macintosh Technical Notes. 

A designation like “(QT 4)” after a 
reference to a jVlacjntosh Technical 
Note or Macintosh Technical Q&A in 
dei^eiop indicates the category and 
number of the Note on this issue's CD. 
(QT is the QuickTime categoiy\) The 
new (un categorized) Tech notes are 
designated by number alone, 

l-mail addresses. Many e-mail 
addresses that are mentioned in develop 
are AppleLink addresses. On the 
Internet, AppleLink address XXX 
translates to xxx@applelink.apple.com, 
NewtoirMail address XXX translates to 
xxx@on 1 i n e. a ppl e *coni. 


CONTACTING US 

Feedback. Send editorial comments 
or suggesrions to Caroline Rose at 
AppleLink CROSE, Internet 
crose@applelink.apple.com, or fax 
(408)974-6395. *Send technical 
questions about develop to Dave 
Johnson at AppleLink JOHNS ON. DK, 
Internet dkj@apple.com, CompuServe 
75300,715, or fax (408)97^-6395. Or 
write to Caroline or Dave at Apple 
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Caroline Rose at the above atldress. 
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the Apple Developer Catalog (see 
ordering information below) or use 
the subscription card in this issue. 

You can also order printed back issues 
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subscription price Is $30 (fur 4 issues and 
4 develop Bookmark CDs), or U.$. $50 in 
other countries. Back issues are $13 
each. These prices include shipping 
and handling. For C'anadian orders, 
the subscription price includes GST 
(R100236199). 

Apple Developer Catalog. To 

order develop or other products through 
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5 GeneraHng QuickTime VR Movies From QuickDraw 3D by Pete Falco and 
Philip McBride 

Qiiick'l'ime V"R movies doiVc have to be created with a real camera; you can instead generate die necessary 
images with a 3D graphics system like QuickDraw 3D. Here’s how. 

29 Flicker-Free Drawing Wifh QuickDraw GX by Hugo M. Ayala 

This article discusses the causes of flicker m graphics and animation applications and presents a package for 
doing memory-efficient, flicker-free drawing with QuickDraw GX. 

48 NURB Curves: A Guide for the Uninitiated by Philip J. Schneider 

QuickDraw 3D includes NURB curves among its geometries, but you need to understanil a little about die 
underlying NURB model to use them effectively. This intuitive treatinent of NURB curves tells you what 
you need to know. 

7B Using Exceptions in C by Avi Rappoport 

Exceptions in C++ provide a powerful and useful way to handle errors and other unexpected conditions. But 
C programmers can take advantage of them as well, since C is (mostly) a subset of C++. 

90 Country Stringing: Localized Strings for the Nev/ton by Maurice Sharp 

Although version 1,5 of the Newton Toolkit provides some built-in support for localizing strings, organizing 
the different sets of strings is still problematic. Or rather, it was until now. 
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EDITOR'S NOTE 



CAROLINE ROSE 


Vd like to make some general comments on user interface tliat IVe been collecting 
for a while. Please understand I don’t claim to be an expert on the subject — and, as 
always, the usual disclaimer applies tliat my opinions aren’t necessarily those of Apple 
Computer the corporate entity* Vm just one person who has the luxury (as well as the 
burden) of filling an editorial page, and this is what’s on my mind. 

First rd like to make a pitch for a more obvious and responsive channel for users to 
give feedback on the experience of working with your software: V\Tiat bugs them 
about it? Do they have suggestions for improvement? It seems that such feedback 
gets lost if it’s delivered through the usual customer support (bug-reporting) vehicle. 
Or maybe it gets delivered to the wrong person, like the engineer who designed and 
implemented that feature in the first place and can give 99 excellent reasons for why 
it was done that way. When I first returned to Apple from NeXT and had to use a lot 
of new applications, I encountered a number of interface glitches that were short of 
being bugs but made using the applications unnecessarily awkward, I suggested a 
few simple fixes through the customer support line, sensing some interest but die 
assignment of a low priority, Alas, diose annoying features are all sdll there five years 
and a couple of upgrades later. 


This ties in with a peeve that 1 share with many of my computer-using friends who 
don’t work in this intlustry and so have that vaiuahle pei^pective of a pure end user: 
Please avoid making spurious interface “improvements” that change die basic way 
I work with your application. Be sore there’s a real benefit to the user before you 
change command names, rearrange them in menus, or put new features in niy face 
rather than making them options I can explore at will. You may think you’re making 
the interface friendlier, but in fact you may be alienating your existing customer base. 
The changes diat 1 most appreciate arc those that smooth out the rough spots of 
die interlace as it is, so that, for example, I won’t have to resize every mail window 
to fit my screen, or select the text in the Find l}f>x every time 1 do a new search. I 
want these nuisances eliminated; instead, I find the upgrade to be just another big 
nuisance. 


We intemipt this list of grievances to announce another list we just learned about: 
develop has been chosen by Internet Valley, Inc, as one of the top 100 computer-related 
magazines and journals on the Web (hrtp://www.intLTnetvalley.com/top 100mag.html). 
Pm happy enough about this tt> quit my griping alnmt user interface for now — 
though I do see a tie-in here: weVe always encouraged and responded to comments 
from our readers, and we’ve tweaked our content and format accordingly rather than 
done a complete overhaul. Thanks for all the valuable feedback over die years; please 
keep it coming so that we can keep improving. 


Caroline Rose 
Editor 


CAROLINE ROSE [AppleLink CROSE) has been 
a fechnical editor For so long fliot she says she 
can do it with her eyes dosed. And that's exactly 
what she dtd after being felled by a detached 
retina during her last vacotion. Lying down for 
over two weeks with her lids shut and not much to 


do except listen to books on tape, she welcomed 
the occasional phone coll on o deve/op-related 
editorial question. Getting back to work and 
realizing how much catching up she had to do 
was □ real eye-opening experience.* 


2 develop lisve 25 Morch 1996 










LETTERS 


WEB FIRST, THEN PRINTED COPY 

develop is absolutely the coolest 
publication for a Mac developer. I 
thought I would drop a line to say 
“thanks” for putting the next issue up 
on die Web a full month before it will 
arrive at iny home. At least this way I 
can get a partial fix! 

Good job! 

— Rob Newberry^ 

I just noticed chat youVe released 
develop Issue 24 online, Tm a subscriber, 
yet I have to call or send e-mail to you 
each time to remind you to send my 
issue! 

Your magazine is terrific, but the service 
is quite the opposite. 

'— Carl Limisco 

As a service to developers who may want 
access to mitent as soon as it's finalized, 
develop content is uploaded to the Web 
within three days of issue completion. 

The print and CD-ROM production 
processes, however, cotistmte more time 
and thus result in the delay between when 
you may first see contetit on the Web and 
when you receive your copy with its CD 
in the mail 

In the case of Issue 24, this period was 
extended due to technical difficulties with 
generating the mailing information. 
Starting with Issue 23, we switched to 
APDA for distribution o/develop. There 
have been a few mags in the transition, 
but we^re confident that subscribers will 
experience i?np?-oved se^wice. Meanwhile, 
we apologize for any pfvblems. 

— Diane Wilcox 


PUZZLE PAGE SLIP UP 

When I received develop Issue 24,1 was 
shocked to find a bug in the Puzzle 
Page. When BAL is explaining how 
LockPixels and UnlockPixels work, he 
mentions that the PixMap baseAddr can 
be either a handle or a pointer, and tliat 
a flag in rowBytes identifies which state 
the baseAddr is in. This is wrong; that 
information is stored in the pm Version 
field of the PixMap. There aren’t any 
bits to spare in rowBytes. 

Other than that, it was a great Puzzle 
Page, as usual 

— Cameron Esfahani 

You^re right;you caught thkslip-up by the 
piizzlemeisters themselves. Say, if you're so 
good, why not write your mvn Puzzle Page? 
[Readers: See the puzzle Camefvn coauthors 
in thk issue.] 

— Caroline Rose 

MULTIPANE FIXES — AND 
ABOUT USING OUR CODE 

The code accompanying Norman 
Franke’s article on multipane dialogs 
(develop Issue 23) is great. I had it up and 
running in a PowerPlant application in 
less than an hour. But 1 found some 
hugs; for example, in the routines 
T2PMPDAction and friends, you lock 
down theData, and I suspect you should 
be locking down tmpData, Before I get 
down and dirty, I was wondering if you 
knew of any other bugs already present. 

Also, the code needs an extra routine 
to generate the data handle without 
displaying the dialog so that one might 
set the initial values (as opposed to 
using factory defaults). 


SEND US YOUR EXCUSE FOR NOT WRITING 

Welf aduQlly we'd rather receive letters regarding 
articles published in develop. Letters should be 
addressed to Caroline Rose — or, if technical 
deve/opreloted questions, to Dave Johnson — at 
AppleLink CROSE or JOHNSON.DK (Internet 
crose@Q pp [el i n k. a p p I e. CO m or d k [@a pple. com). 


All letters should include your name and company 
name as well as your address and phone number. 
Letters may be excerpted or edited for clarity (or 
to make them say what we wish they did]. Please 
send all subscription-reiated queries to AppleLink 
APDA (Internet apda@applelink.Qpple.com].* 
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When I get the PowerPlant classes 
working and debugged, Fd like to 
distribute them on the Internet (free). 
May I include your code (possibly 
modified)? 

Again, thanks for a great article. 

— Gordon Watts 

Nofyfian has provided a newer version of bis 
code as ofisstte 24V CD. He'^s fixed a lot of 
btt^ and also now provides PowerPlant 
classes; see the README file for details. 


You may redisirihite the MPDialogs source 
if you like^ as long as ifs part of your mvn 
thing and not just a redistribution of the 
original package. For iitstancey youHl 
probably not be distributing Nofinmfs 
sample or its source^ hutjmt the files 
MPDialogsxandMPDialogs.k Please 
include a pointer to where they camefi^om, 
since prewmably the code will change over 
time (bugfixes and so on). 

By the way, you imi contact Norman 
directly at Jranke@eworld.com. 

— DaveJohnsojj 


TECHNOTES AND Q&AS: BEHER THAN EVER 


The observant among you will notice a change in 
Technical Notes on this issue's CD (and on the World 
Wide Web and the other myriad places where they can 
be found). The old Mocintosh Technical Notes ore still 
around, but now there ore also new Notes, going simply 
by the name 'Technotes." The old Notes will eventually 
evolve into the new scheme. We to Iked with Tech note 
leader Tom Maremaa, from Apple's Developer Technical 
Support group, for the scoop on this. 

"The old Notes hove a rich and varied history at Apple, 
and hove served developers well fn the past," Tom said, 
"We wanted to continue that tradition ^— but with 
changes, something on the order of Technofes: The Next 
Generation f 

First, Tom hopes you'll agree that the biggest improvement 
is in the quality of the new Technotes. They receive for 
more review by Apple engineers than the old Notes did, 
and they're better edited and formatted, so you should 
find them a lot more readable and reliable, Technotes will 
also be timelier: more of them will focus on hot new 
technologies, such os QuickTime VR and QuickDraw 3D, 
with updates ond odditfons posted regularly on the Web 
at http://dev.info,apple.com/technotes/Main.html. 

They'll migrate to c/eve/op's CD and other such locations, 
but you'll no longer hove to wait thot long for the latest 
and greatest Information. 

You'll notice that Technotes are numbered sequentially, 
starting from 1001, rather than divided into functional 
categories. Tom found that placing o Note into a single 
category was becoming increasingly difficult and arbitrary; 
often a topic would span more than one category or 
wouldn't quite fit into any existing category, locating a 


Note on a particular subject is easier than ever thanks to 
the improved searching tools that are now available: you 
can use Acrobat's search mechanism on the CD or the 
excellent search facility provided on Apple's Web pages. 

"Providing developers with the obility to search fast ond 
effectively through the whole body of Technotes, 
particularly on the Web," said Tom, "has been a major 
gcx]l in the project. It's there now. Check it out!" 

The old Macintosh Technical Notes ore gradually being 
cleaned up: over time they'll be updated and worked into 
the new scheme, or deleted if obsolete. Should you look 
for an old Note by category and number, you'll find a 
"stub" indicating its current status if it's been revised or 
removed. In particular, the old Q&A Technicot Notes are 
being discontinued; new Q&As are being released as 
"Macintosh Technical Q&As" (they're on the Web at 
http://dev. Info-applexom/techqa/Maln.html). 

For those of you who like to hove Notes in printed form, 
you can still order a printed copy (of both the old ond the 
new Notes). See the Technotes Web page or the latest 
Apple Developer Catalog for details. 

Finally, Tom would like to point out that Technotes con be 
submitted by outside authors (although Coroline asks that 
you Rrst consider whether develop might be o more 
appropriate vehicle for your handiwork If your Note is 
published, you'll receive YATS (Yet Another T-Shirt) along 
with some other goodies, including a chonce to participate 
in Apple developer kitchens and other special events. For 
more information, or just to let us know what you think of 
all these changes, write to AppleLink DEVFEEDBACK 
(devfeedback@applelink.apple.com). 
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PETE FALCO AND 
PHIUP MCBRIDE 


QuickTime VR Movies From 
3D 


QuickTime VRis a new technology from Apple that provides users 
with a virtual reality experience through interactive panoramic atid 
object movies. You can generate images for QuickTime VR movies 
with either a real camera or a three-dim-ensional rendering system 
such as QuickDraw 3D. Here you'll learn how to create images from 
QuickDraw 3D models and generate movies from these irnuges with 
the QuickTime VR Authoring Tools Suite version 1.0. 


Quicklime VR lets you create two kinds of interactive virtual reality movies: 
panofmnk movies and object movies. In a panoramic movie, users can interactively view 
a scene at nearly aU camera angles from a particular point in space, which gives them 
the impression of being there and looking around. In an object movie, users can 
interactively spin an object around and diereby see it frt>m all sides. Panoramic and 
object movies can lie linked tcigether or used separately. 

QuickTime VR has several advantages over three-dimensional modeling systems for 
making interactive movies. Its movie files are much smaller than complex 3D models 
in situations where complete interactivity with the scene isnk necessary nr where the 
scene contains complex c^hjects or large numbers of texmres. With Quick'rime VR, 
the complexity of the .scene and the number of texmres used are irrelevant to runtime 
performance, so even users with lower-end machines can effectively interact with the 
scene. Finally, a QuickTime VR scene needs only a few megabytes of free space in 
memory, much less than the enormous amaum of RAM usually taken up by complex 
3D scenes. 

You can create QuickTime VR movies using eidier digitized images captured from 
a real camera or sjmthetic images generated by a 3D rendering system, such as 
QuickDraw 3D. In this article, youll learn how to generate images with QuickDraw^ 
3D and convert them to QuickTime VR movies. To make a panoramic movie, you 
create a panoramic image from a 3D scene, generate a linear QuickTime movie from 
the image, and convert the linear movie to an interactive panoramic movie using the 


PETE FALCO (AppleLink FALCOP] is a member oF 
Apple's QuickTime VR team. Since finishing school 
of Rensselaer Polytechnic Institute in upstate New 
York, where he spent the last six years in the 
rainy, snowy weather of Troy, he's found the 
sunny weather of California a wekome treat ond 
vows hell never leave this area. His latest 
projects include working on the next release of 
QuickTime VR os well os integrating all of Apple's 
multimedia technologies with QuickTime VR.* 


PHILIP MCBRIDE (mcbride@apple.com) has been 
working on multimedia tools and the underlying 
media technologies since he's been at Apple. Most 
recently this included helping to add QuickTime 
VR to Apple Medio Tool 2.0. While not working 
with digital multimedia, Philip likes to work with 
real multimedia by sculpting. In Fact, he's been 
developing □ new product that will involve cloy, □ 
mouse, and a bottle of cabernet. The detoils are 
sketchy, but he has a cool T-shirt for it.* 
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QuickTime VR Authoring Tools Suite (ATS)* (The ATS is a set of tools that you use 
from within MPW, the Macintosh Programmer’s Workshop*) To create an object 
movie, you generate a series of images from a 3D model, add the images to a linear 
QuickTime movie, and then use the QuickTime VR ATS to convert the linear movie 
to an interactive object movie* 

Before we get into the specifics of making movies, well explore the basic concepts of 
QuickTime VR. We assume you have a general understanding of QuickDraw 3D, 
which you can get by reading “QuickDraw 3D: A New Dimension for iMacintosh 
Graphics” in develop Issue 22 and “The Basics of QuickDraw 3D Geometries” in 
develop Issue 23. You can learn all about QuickDraw 3D in the book iD Graphics 
Programming With QuickDfmv 3D. 

This issue's CD contains all the code necessary to generate panoramic images and 
linear object movies from QuickDraw 3D models. For brevity, the listings in the 
article omit error handling; die code on the CD includes the complete versions of 
these fimctions* 

QUICKTIME VR BASICS 

The basic components of QuickTime VR movies are pamnamas, nodes, objects, and 
scenes, 

• A paftorama is an image spanning 360° or less in a real or virtual scene. The 
image is viewed from a particular location in the scene, called a node. A 
single-node panoramic movie enables a user to look in all directions from 
diat location. 

• An object is an interactive item that can be viewed from all angles* Object 
movies can be linked to panoramic movies in a scriptahle authoring 
environment, enabling a user to pick up and turn die objects from within a 
panorama* Object movies can also be used independently of panoramic 
movies* 

In our case, the object of the movie is generated from a QuickDraw 3D 
model, which contains a single geometric object (or group of objects); we’ll 
use the term model in this article to refer to the object in a Qiiickrime VR 
object movie* 

• A sce?ie is a collection of several panoramas or nodes, a panorama with one 
or more objects, or several panoramas and objects all linked together by 
interactive hot spots* In a multinode scene, a user can na\igate from node to 
node to move about the scene. 

SHOOTING AN OBJECT 

For object movies, you need to photograph the model (or the real object) from all 
directions, as shown in Figure I * All vertical camera positions above the center of the 
model are considered positive, and all positions below it are considered negative. The 
vertical position with the camera directly above die model looking down at it is called 
vertical pan 5^0°; the vertical position direedy below and looking up is called vertical 
pan Vertical pmt is at the modeFs center (equator)* Horizontal positions are 
measured in degrees from borizomalpan 0° to 360°. Horizontal pan 0° is typically at 
the back of the model. 

Images must be stored as frames in row order from top to bottom in a linear QuickTime 
movie. For best results, we (along with the QuickTime VR documentation) recommend 
that you have a frame every 10° between positions in both the horizontal and vertical 
direction. If you shoot at increments greater than 10°, the motion of the model in the 
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Figure 1, Shooting a model (or a real object) 

QuickTime VU movie will be choppier when the user turns it. If you shoot at 
increments of less than 10°, die motion will be smoother, but you’ll need more disk 
space to store all the frames. Whatever increment you choose, it should be consistent 
between all horizontal and vertical frames for the object and divide evenly into the 
horizontal and vertical pan ranges. 

Your first frame at each horizontal position should be of the hack of tiie model, so 
that the frame showing the front of the model is halfway tiirough the series at that 
horizontal position. This improves <lisk access time at run time since the user will 
most likely be looking at the front of the model. 

SHOOTING A PANORAMA 

If yemVe using a real camera to shoot a panorama, you need to take the appropriate 
number of equally spaced pictures in a circle, as shown in Figure 2. 



Figure 2. Shooting o panorama 

Although this sounds simple, there are a few things you must be aware of. First, you 
need to make sure youVe taking the right number of shots for the lens you’re using 
(see Chapter 6 in Volume ! of the QuickTime ATS documentation for a full 
explanation of this). The entire camera rig should be level at all times, and the nodal 
point of the lens should be directly over the point of rotation of the rig. For best 
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results, you should also have a consistent overlap bemeen images; the more overlap, 
die better (30% to 50% is recommended). Finally, you should maintain consistency 
beween images in each panorama by using similar exposure and a fixed focus. 
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Because this can get quite complicated, Apple strongly recommends the use of a 
professional photographer for making any production-quality titles. However, one 
way around this is to use rendered data, as we do in this article. The programmatic 
control we have over the “virtual” camera in a 3D environment such as QuickDraw^ 
3D eliminates all of the problems just mentioned. 

MAKING MOVIES WITH THE SAMPLE CODE 

The sample code on this issuers CD enables you to make object and panoramic movies 
from any 3DMF file (a file that conforms to the QuickDraw 3D Object Metafile 
standard). For either type of movie, the code creates a new document record structure, 
reads in the model from a 3DM1" file, renders the images, and writes out the images 
in a fonn that the QuickTime VR tools can w^ork witli. 

Here well look at the first few steps, which are common to both types of movies. 

The other steps for making QuickTime VR movies — rendering and writing out tiie 
images and converting linear movies to interactive movies ’— are different for object 
and panoramic mtwiemaking and are described later. 

CREATING A NEW DOCUMENT 

Ml of our scene information is stored in a document record someture, shown in 
Listing 1. 


Listing 1. The documenh record structure for a scene 
typedef struct _DociirnentRecord { 


CWindowPtr 

theWindow; 

// 1 

FSSpec 

theFileSpec; 

a \ 

short 

fRefMum; 

n . 

GWorldPtr 

drawContextOf f Screen; 

// ( 

TQ3Group0bject 

do cumen tGrou p ? / / 

Mai: 

TQ3View0bject 

theview? // 

The 

TQ3Matrix4x4 

modelRotation; 

// ' 

TQ3Point3D 

documentGroupCenter ; 

// ( 


// Miscellaneous view, modeli and QuickTime file details 
} DocumentRecord, ^DocumentPtr, **DocumentRandle? 


The MyNewDociiniern fimetion (Listing 2) creates the document record structure 
and sets up the view, camera, and other elements associated with the scene. It also 
adds the background buffer and window' used to display the rendered images of the 
scene. 

CREATING THE CAMERA 

llie camera used to render the images for die movies is created by the MyNewCamera 
function, shown in Listing 3. 

For object movies, we set the field of view to approximately 30'^. This is not a fixed 
number; you can use any number that you see fit, based generally on the aspect ratio 
of your viewing window and how' much information you'd like to display inside it. 
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Listing 2. Creating a new document record structure 


Doc ume nt Ptr MyNewDoc ume n t { ) 
{ 


DocumentPtr 

CWindowPtr 

TQ3DrawContext0bject 

Rect 

TQ3CameraObject 
RGBCoIor 


theDocument; 

theWindow? 

theDrawContext j 
itiyBounds = kMy Bound a Rect; 
camera = HULL; 
blackColor = kMyBlackColor; 


theDocument = (DocuinentPtr)NewPtrClear(8izeof(DocumentRecord)}; 

// Create the window for the document record and add references to 
// the document record* 

theWindow = (CWindowPtr)NewCWindow(OL, SmyBounds, 

"\pRendering Window", true, documentProc, (WindowPtr)-lL, 
true, NOLL); 

theDocument->theWindow = theWindow; 

// Create and set up the offscreen GWorld/context* 
if ** Notice that QuickDraw 3D prefers direct color* ** 

NewGWorld{ S!theDocuiuent->drawContextOffScreen, 32, 
fitheWindow->portRect, nil, nil, OL); 

SetGWorld(theDocuinent->drawContextOffScreen, nil); 

Erase Rect(& t heDoc ume nt->dr awCon te x tOf fS cre e n- >pG rtRec t); 

// Create the new pixmap draw context- 

the D rawCon text = MyN ewDr awContext(the Docume nt); 

// Create the view and set up the view attributes. 

// Initialize the model rotation and transitions used for object 
// movie rotations. 

Q2 Ma t r lx 4 x4_S et I de n t i ty (& t heD oc ume n t- >mode IRot at ion); 

// Add more model and view properties to the document record- 

// Create the camera and add it to the view* 
camera = MyNewCainera(theDocument->theWindow); 

Q3View_SetCamera(theDocument->theView, camera); 

Q30bject_Dispose(camera); 

// Add the Tenderer to the view* Set the window*s GWorld* 
Q3View_SetEendererByType(theDocument->theView, 
kQ3RendererTypeInteractiveJ; 

SetGWorld(theWindow, nil); 

return (theDocument); 
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Listing 3, Creotmg the rendering camera 

TQ3Camera0bject MyNewCamera(CWindowPtr theWindow) 

{ 

TQ3ViewAngleAspectCameraData perspectiveData; 

TQ 3 C ame r aOb j ect c amera; 

// For object movies, we set the field of view to 30 degrees (or 
// 30•0*kQ3Pi/180.0 radians). For panoramic movies, we set it to 
// 74 degrees (or 74*kQ3Pi/180.0 radians). QuickDraw 3D requires 
// angles to be in radians, while QuickTime VR requires them to 
//be in degrees, 

float fieldOfView = 30»0*kQ3Pi/lBO,0? 

TQ3Status returnVal = kQ3Failure; 

// Assign default placement. 

perspectiveData.cameraData.placement.cameraLocation = kMyDefaultFrom? 
perspectiveData.earneraData.placement.pointOfInterest - kMyDefaultTo; 
perspectiveData.earneraData.placement.upVector - kMyDefaultUp; 
perspectiveData.cameraData.range.hither = kHyDefaultHither; 
perSpectiveData.earneraData,range,yon = kMyDefaultYon? 

// Assign standard view port, 

perspectiveData,earneraData.viewport.origin.x = -1.0; 
perspectiveData,cameraData.viewport,origin.y = 1,0; 
perspectiveData,cameraData.viewport.width ^ 2.0; 
perspectiveData,earneraData.viewport.height =2.0; 

perspectiveData-fov = fieldOfView; 
perspectiveData.aspectRatioXToY = 

(float) (theWindoW">portRect.right - theWindDw->portRect.left) / 
(float) (theWindow->portRect.bottom - theWindow->portKect,top); 

camera = Q3ViewAngleAspectCamera_Kew(&perspectiveData); 

return (camera); 

} 


Fnr panoramic movies, we set the field of view to 74"^. This matches the horizontal 
field of view of a I5nim lens for our image. We specify the horizontal rather than 
vertical field of view since our image is taller than it is wide (768 x 512 pixels), and 
QuickDraw 3D requires the field of view to he specified as that of the shorter side of 
the image (whether width or height). We calculate the horizontal field of view based 
on the size of our image and the known vertical field of\new of a 15mm lens (97°, as 
specified in Chapter 9 of the QuicDFime VR ATS documentation). 

READING IN THE MODEL 

For the model to be read from a 3DMF file, you must first create 3D file and storage 
objects associated widi that file. Once theyVe been created, you Imild up the model 
by reading in all the draw able objects from the file and adding tliem to a group, as 
shown in Listing 4. 
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If the model includes any lighting, we use those lights; otherwise we create our own 
lighting for the model. 






Listing 4. Reading in the model 


TQ3Statas MyReadScene(TQ3FileObject file, DocumentPtr theDocument) 


TQ30bject 
TQ3Boolean 
TQ3ViewObject 
TQ30bject 
TQ3Gronp0bject 


object; 
isEOF; 
view; 
model; 

lightGroup = NULL; 


// Create the new model and get the view, 
model = Q3DisplayGroup_New(); 
theDocuiiient->documentGroup = model; 
view = theDocument->theView; 


// Collect all drawable objects (into the model) and collect any 
// lights (into the lightGroup). 

while ((isEOF ^ Q3File_IsEnd0fFile(file)) kQ3False) { 
object = Q3File_Read0bject(file); 

if (Q 3 Ob j ec t_IsDrawab1e(ob j ect)) 

Q 3 Group_AddOb j e ct{mode1, ob j ect); 

if (Q30bject_lsType(object, kQ3SharedTypeViewHints)) 
if (view) 

Q 3 ViewHint sjGetLightGroup((TQ3 ViewHint s Ob j ec t)ob j ec t, 
SlightGroup); 

if (object != NULL) 

Q30bject_0ispose(object); 

// Add any lights found to the view* Otherwise create default lights, 
if [lightGroup) { 

Q 3View_S e tLightGr oup(view, 1ightGrou p ); 

Q 3 Ob j e c t_p i spo se (1 i ght G roup ); 

> 

else 

HyNewLights(theDocument); 

Q3FilejClose(file); 
return kQ3Success; 


GETTING THE DIMENSIONS OF THE MODEL 

We must know the dimensions of the entire model as well as its center in order to place 
the camera in its mitial position and to guide both camera and model transformations. 
You obtain the dimensions and center of an already constructed model by getting the 
moders hounding sphere with the ftinction MyGetBoundingSphere (Listing 5)* The 
bounding sphere is another 3D object that fully surrounds the model and has as its 
center the exact center of the model. 

For object movies, the bounding sphere has an additional purpose. A]though a 3D 
model from a QuickDraw 3DMF file may contain more than one geometric object, 


GEMERATING QUICKTIME VR MOVIES FROM QUICKDRAW 3D IT 





Listing 5. Getting the model's bounding sphere 

void MyGetBoundingSphere(TQ3View0bject viewObject, TQ3GroupObject 
mainGroup, TQSBoundingSphere *viewBSphere) 

{ 

TQ3Status status; 

Q3View_StartBoundingSphere(viewObject, kQ3ConiputeBoundsApproximate); 
do { 

status = Q3DisplayGroup_Submit{mainGroup, viewObject); 

> while (Q3View_EndBoundingSphere(view0bject, viewBSphere) ^ 
kQ3ViewStatusHetraverse); 


a QuickTime VR object movie has only one geometric object or one group of objects. 
Thus^ we use the bounding sphere to get the dimensions of the entire group of objects, 

MAKING A QUICKTIME VR OBJECT MOVIE 

Now' we^ll get into the specifics of making a QuickTime VR object movie. The 
MyConvertSDxMFToObject function (shown in Listing 6) drives the entire process, 
from creating the new' dt>cument to generating the linear object movie. You use the 
QuickTime VR ATS to generate an interactive object movie from tliis linear movie. 


Listing 6. Converting 3DMF files to linear object movies 

void MyConvert3DMFTo0bject{FSSpec *myFSS) 

{ 

DocumentPtr theDocument; 

// Create the docuinent record and make the view, camera, lights, 
// window, and so on. 
theDocumant = MyMewDocument(); 

// Read in the model and add it to the document recordgroup. 
MyOpenFile(myFSS J; 

// Set up the initial camera position. 
MyInitObjCamiera{theDocument); 

// Draw initial view to the screen. 

MyDrawOffScreen(theDocument); 

MyDrawOnScreen(theDocument); 

// Assign the codec type. 
theDocument->theCodecType = kMyCodec; 

// Generate all the images and add them to the movie. 

MyGenerateObjImages(theDocument, 36, 19, 360, 0, 90, -90); 

} 
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DOING THE MODEL AND CAMERA WORK 

Photographing a real object involves using a spherical camera rig to rotate a camera 
around the object. For 3D models, it’s just as easy to rotate the model in front of a 
stationary camera. Furthermore, since the camera doesn’t move in this case, the 
lighting is easier to manage because it doesn’t need to be rotated with the camera 
(unless you want the object to appear to be lighted from a certain angle). 

In our case, we’ll render images of the model by rotating the model around two of its 
axes while the camera views it from the third axis; thus the camera gets a view of the 
model from every angle. In our case, we’ll place the camera along die z axis and 
rotate the model around the x aiidj axes. The initial positions of the camera and the 
mode! can be seen in Figure 3. 


y 



Figure 3* Initial positions of the comero and the model for object movies 

The initial placement of the camera for an object movie is performed by the frmctifjn 
MylnitObjCamera, shown in Listing 7. First we get the bounding sphere of the 
drawable group of the model. From this we can get the center 3D point of the 
drawable group (as the origin of the bounding sphere) and the radius. From the 
center point we place the camera a distance of five times tiie radius down the z axis 
from the object. 

We rotate the model by repeatedly modifying the modePs transform object. The 
function MyRotateObjectX rotates the object around its x axis (see Listing 8). An 
analogous function that’s not shown here, MyRotateObjectY, rotates it around the 
y axis. 

We step through the model rotations to create the images needed for the linear 
object movie with the MyGenerateObjImages frmction, shown in Listing 9. In this 
function, we iterate over y angles (rotating around the x axis) while iterating over 
X angles (rotating around the y axis). This stepping takes us from the position 
yAngie = max VP an, xAngle = minHPan to the position yAngle = minATan, 
xAngle = maxHPan - minHPan. At each step in the x and y angles, the model is 
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Listing 7. Setting l^he initial camera position for on ob|ect movie 

TQ3Point3D MyInitObjCamera(DocumentPtr theDocument) 

TQ3BoundingSphere viewBSpherer 

float viewRadius; 

// Get the bounding sphere of the drawable group (the entire model) 
//in the view, 

HyGetBoundingSphere(theDocument->theView # theDocuinent->documentGroup, 
&viewBSphere)j 

// Get the bounding sphere's center and radius. 
theDocument->docmiientGroupCenter = viewBSphere. origin; 
viewRadius ^ viewBSphere.radius; 

// Position the camera down the z axis from the bounding sphere based 
//on the center and the radius. 

MyPlaceCamera(theDocument, theDocument->docQmentGroupCenter.x, 
t he Doc ume nt->do cumen tG r oupC ente r.y, 
theDocument->documentGroupCenter.z + 

kMyDistanceFactor*viewRadius + 1,0, 
theDocuinent->dDcumentGroupCenter. x, 
theDocument->documentGroupCenter.y, 
theDocument->dDCuinentGroupCenter, z + 
kMyDietanceFactor*viewRadius); 

return (theDocunient->documentGroupCenter); 

> 


Listing 8. Rotating the model for object rendering 

void MyRotateObjectX(DocumentPtr theDocument, float angle) 

TQ3Matrix4x4 tempMatrix; 

G3Matrix4x4_SetTranslate(&tempMatrix, 

-theDocument->documentGroupCenter, x, 

-1h e Do cument->do c ume n tGrou pC e nt e r.y, 

-theDocument->documentGroupCenter.z); 

Q3Matrix4 x4_MuItiply(& theDocument^>mode1Rotation, & tempMatrix, 
&theDocument'>modelRotation); 

Q3Matrix4x4_SetRotate_XYZ(&tempMatrix, angle, 0.0, 0.0); 

Q3Matrix4x4_Multiply(&theDocument->modelRotation, atempMatrix, 
&theDocoment->modelRotation); 

Q3Matrix4x4_SatTranslate(&tempMatrix, 

theDocument->documentGroupCenter.x, 
theDocument->documentGroupCenter.y, 
theDQCument->documentGroupCenter.z); 

Q3Matrlx4x4_Multiply {&theDoGumerit->modelRotation, &tempMatrix, 
S theDocument->iiiodelRotation); 
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Listing 9* Generoting images for the linear object movie 

void MyGenerateObjlTnages(DocunientPtr theDocument, short rows, short 

columns, long maxHPan, long minHPan, long maxVPan, long ndnVPan) 

( 

float xStart, yStart, xStep, yStep, xAngle, yAngle; 

// Assign stepping angles, 

yStep ^ ({float) (maxVPan-minVPan)) / (float) (rovrs-1); 
xStep = ((float)(maxHPan-minHPan))/(float)(columns-1); 

HyPrepareDestMovie(theDocument); 

for (yAngle ^ maxVPan; yAngle >= minVPan; yAngle -= yStep) { 

for (xAngle = 0; xAngle <= maxHPan-minBPan; xAngle xStep) { 

// Rotate the object to the correct position. 
xStart = (-kQ3Pi*(xAngle - 

((float)(maxHPan-minHPan))/2.0))/180.0; 
yStart = kQ3Pi*((float)yAngle)/ISO.0; 

MyRota teOb j ectY{theDoc ume nt, xStart); 

MyRotateObjectX(theDocument, yStart); 

// Render the model (to get a PixMap image)• 

MyDrawOffScreen(theDocument); 

MyDrawOnSereen(theDocument); 

if Add the rendered PixMap image to the movie. 
MyAddIi!iageToMovie( theDoemnent); 

// Undo the rotation. 

MyRotateObj ectx(theDocument, -yStart )i 
MyRotateObjectY(theDocument, -xStart); 

> 

> 

MyCloseDestMovie(theDocument); 


rotated and then rendered. The resulting images are added to a previously created 
movie, as described in the next section. Note that QuickTime likes angles 
in degrees and QuickDraw 3D likes angles in radians, so we have to do these 
conversions. 

CONSTRUCTING THE UNEAR OBJECT MOVIE 

The destination movie is an ordinary QuickTime movie. The movie file, track, and 
track media need to be set up before rendered images can be added to the movie. The 
images are added as frames to a track. (See huide Mannmh: QuickTime for more details 
about this process.) The movie is constructed in the function MyPrepareDestMovie, 
shown in Listing 10. 

We add die rendered images to the movie with the QuickTime function 
AddMediaSaniple, which is called from within the frmetion MyAddlmageToMovie 
(Listing 11). MyAddlmageToMovie is called after each model rendering, as seen 
earlier in the MyGenerateObjImages frmetion. 
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Listing 10- Creating the destination lineor object movie 


OSErr MyPrepareDestMovie(DocumentPtr theDocument) 


long 

short 

CodecComponent 

FSSpec 

Timescale 

TimeValue 

CodecQ 

Str255 


keyFrameRate, compressedFrameSize ; 

frameRate^ widths height, i; 

theCodec; 

theFSSpecj 

dstTimeScale; 

duration; 

spatialQuality; 

movieName == "\pObjectHovie'’? 


keyFrameRate =1; // Every frame must be a key frame. If 

// not, we'll get garbage around the edges 
// of our objects when we rotate them. 

// QuickTime refreshes only key frames 
// completely. 

theCodec = anyCodec; // We'll use what’s there 

spatialQuality = codecHighQuality; // and make it look pretty, 
frameRate =10; // This can be any value. 

dstTimeScale =600; // This can be any value that^s a multiple 

// of frameRate. 

duration = dstTimeScale/frameRate; 


width = theDocument->theWindow->portRect,right - 
theDocument->theWindow->portRect.left; 

height = theDocument->theWindow~>portHect.bottom - 
theDocument“>theWindow->portRect,top; 

theFSSpec = theDoGument->theFileSpec; 

BlockMove{movieName, theFSSpec.name, movieName[0]+l}; 

CreateMovieFile(ttheFSEpec, creatorType, 0, 

createMovieFileDeleteCurFile, &theDocument->dstMovieRe fNum, 
&theDocument->dstMovie); 

theDocument->dstTrack = NewMovieTrack{theDocunient->dstMovie, 

((long)width) « 16, ((long)height) « 16, 0); 

theDocument”>dstMedia = NewTrackMedia{theDocument->dstTrack, 
VideoKediaType, dstTimeScale, 0, 0); 

BeginMediaEdits{theDocument->dstMedia); 

GetMaxCompressionSize(theDocument->drawContextOf fScreen->portPixMap, 
Sth8Document->drawContextOffScreen->portRect, 32, 
spatialQuality, t heDocuinent-> the Codec Ty pe, theCodec, 
icompressedFrameSize); 

theDocunient->compressedData = NewHandle (compressedFrameSize) ; 

t he Doc ume nt->c ompres s edD at aPtr = 

StripAddress(*(theDocument->compressedData)); 

HLock(theDoGument->eompressedData); 

theDocument->idh = {ImageDescriptionHandle)NewHand1e(4); 


} 
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Listing 11 - Adding Images to the linear object movie 

OSErr MyAddlmageToHovie (DocunientPtr theDoc\iiiient) 

{ 

CodecQ spatialQuality? 

TimeValue duration, currentTime; 

spatialQuality = codecHighQualityf 
duration ^ 60; 

LockPixels(theDocuraent*>drawCQntextOffScreen->portPiKMapJ; 

Compr es s I mage (th eDocument ->dr a wC o nt extO f f Scr ee ii*>por tP i xMap, 

&theDocument->drawContextOf fScreen->portRect, spatialQuality, 
theDocuitient->theCodecType, theDocument->idh, 
theDocuinent->compressedDataPtr); 

UnlockPixels(theDocument->drawContextOffScreen^>portPixMap); 

AddMediasample{theDociment^>dstMedia, theDocmnent->compressedData, 0, 
(* * (theDocumeitt->idh) J. dataS i ze, duration, 

(SampleDescript ionHandle) theDocmnent->idh, 1,0, & cur rentTicne); 


GENERATING THE INTERACTIVE OBJECT MOVIE 

To generate the interactive object movie, open the linear movie you just created with 
the Navigable Movie Player application (in the QuickTime VR ATS) and choose the 
Add Navigable Data menu item. This brings up the dialog shown in Figure 4. Fill 
in the fields with the values shown and click OK to change the linear movie to an 
interactive movie. Turn the model to tlte position you want it to be in at the 
beginning of the interactive movie, choose the Set Poster View menu item, and 
youVe done! 


Uersion ^ 1 


O Scene 
® Object 
O Object in Scene 


Field Of Uieiii 


TOO 


# Of RotiJS 

# Of Columns 
Loop Size 
Loop Ticks 
Start HPan 
End HPan 
Start UPan 
End UPan 



( Cancel ] [( OK )| 


Figure 4. The Add Navigable Dato dialog 
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MAKING A QUICKTIME VR PANORAMIC MOVIE 

There are two approaches to creating- panoramic movies. One way is to simulate a 
real camera, rotate the camera to generate a series of images, and then “stitch” the 
images cogetlier into a single .^60° panoramic PICT file with the QuickTime VR 
stitching tool. This panoramic picture file can be converted first to a linear movie and 
then to an interactive movie with the QuickTime VR ATS. This is the technique 
welt look at first. You can also render a single panoramic image directly; this avoids 
the need for the stitching tool and enables us to convert the image into an interactive 
panoramic movie with only one line of script. The setup is simitar for both approaches. 

Throughout the QuickTime VR documentation, examples and references assume a 
vertically oriented, 360° full panorama that’s 768 pixels across by 2406 pixels high, 
captured with a IStnm lens using portrait orientation. This is exactly the panorama 
we’ll create. 

Before you begin making the movie, you need to determine the number of shots 
required to make your panorama. For a real 360° panorama, the number of shots is 
a function of the length of your lens and the amount of overlap between the shots. 

For a rendered panorama, however, the number of shots is a function only of the 
horizontal field of view. Because the camera posirion and lighting conditions are 
controlled in the code, overlap bemeen the shots isn’t necessary. You can specify any 
amount of overlap, but theoretically a one-pixel overlap is all that’s required. 

In our case, we’ll simulate the camera that’s recommended in the QuickTime VR 
documentation — that is, a camera with a 15mm lens. To l>e consistent with the 
examples in the documentation, we’ll shoot 12 pictures, each 30° apart. This will give 
us an overlap of about 50%. 

The function MyConvert3DMFroPano {Listing 12} drives the entire panoramic 
moviemaking process. Much like jVIyConvert3OMFItjObject, this function creates 
a tlocLiment, reads in the model, and renders the appropriate images. 

DOING THE MODEL AND CAMERA WORK 

The initial placement of the camera is perfonned by the function MylnitPanoCamera 
(Listing 13). It first gets the bounding sphere of the model’s drawable group, and 
from the hounding sphere gets the center 3D point of the group (as the origin of the 
hounding sphere). Of course, y(iu can place your camera anywhere you like in the 
scene. For simplicity, we placed our camera in the center. From that position, the 
camera is rotated to create the images. 

For panoramic rendering, wc rotate the camera around its y axis with the function 
MyRotaceCameraY, shown in Listing 14. To do the rotation, we do the equivalent of 
translating to local coordinates, rotate, and then translate back to world coordinates. 
We do the transformation by making a rotation matrix about the local y axis (the up 
vector) at our location, getting our local z axis (by subtracting the point of interest 
frojn the current location), anti then rotating die z vector around the y axis. We tlien 
apply this transformation to get a new point of interest. The rectangles encircling the 
camera in Figure 2 represent the images rendered after each camera rotation. 

To create a series of images, we step through the camera rotations with die 
MyGeneratePanoFrames function (Listing 15). Here we rotate the camera 30° at a 
time, render an image, and write the image to a PICT file. This gives us 12 PICT 
files named 01 through 12 that can be used in a very straightforward manner by the 
QuickTime VR ATS. To create a single panoramic image, you use the function 
MyGeneratePanoMovieDirect, as shown later. 
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Listing 12* Converting 3DMF files to panoramic images 

void MyConvert3DMFToPano(FSSpec *inyFSS) 

{ 

Do curae n tP tr the Document; 

// Create the document record, 
theDocument = MyNewDocument(); 

// Head the model into the document record* 

MyOpenFilefmyFSS ); 

// Set up the initial camera position. 

MyInitPanoCamera(theDocument); 

// Draw initial view to the screen. 

MyD r awO f f Screen(theDocumen t); 

MyDrawOnScreen(theDocument); 

// Create a series of images to stitch together into a panorama. 
MyGeneratePanoFrames(theDocument); 

// To create a single panoramic image, call MyGeneratePanoMovieDirect 
// instead of MyGeneratePanoFrames. 

} 


Listing 13. Setting tfie initial camera position for o panaramic movie 
TQ3Point3D MyInitPanoCamera(DocuiiientPtr theDocument) 

TQ3BoundingSphere viewBSphere? 

float viewRadius? 

// Get the bounding sphere of the drawable group (the entire model) 

//in the view. 

MyGetBoundingSphere(theDocument->theView, theDocument->docnmentGroup , 
aviewBSphere); 

// Get the bounding sphere's center and radius. 

theDocument->documentGroupCenter = viewBSphere.originj 

viewRadius = viawBSphere* radius? 

// Position the camera in the center of the bounding sphere. 

MyPlaceCamera{theDocument, theDocument->documentGroupCenter.x, 
theDocument->documentGroupCenter.y, 
thaDocument->documentGroupCenter.s, 
theDocument->documentGroupCenter.x, 
theDocument->documentGroupCenter.y, 
theDocument“>documentGroupCenter.z + 1.0); 

return (theDocument->documentGrQupCenter); 

) 
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Listing 14, RotaHng the camera for panoramic rendering 


void MyRotateCameraY(DociMentPtr theDocument, float dY) 

{ 


TQ3Caniera0bject 
TQ 3 C ame raP1ac erne nt 
TQ3Matrix4x4 
TQ3Vector3D 


camera; 
cameraPos; 
myRotation; 

initia1Vec tor, rotatedVec tor; 


Q3View_GetCamera(theDocument->theVi8w, ^earnera); 

Q3Camera_GetPlacenient{camera, ScameraPoB); 

// Get the z vector. 

Q3Point3D_Subtract(ficameraPos.pointOfInterest, 

&cameraPos. earner allocation, sinitialVector); 

// Rotate around the y axis. 

Q3Matrix4x4_SetRotateAboutAxis{SmyKotation, 

acamer aPos. earner allocation, Scamer aPos. upVect or, dY); 

// Rotate the z vector around the y axis. 

Q3Vector3Djrransform(S(initialVector, &myRotation, &rotatedVector); 

// Get the point of interest from the rotated vector. The upVector 

// doesn’t change. 

Q3Point3D_Vector3D_Add(ficameraPos.cameraLocation, SrotatedVector, 
scameraPos.pointOfInterest); 


Q3Cainera_SetPlacement (c amera, scameraPos); 
Q3View_SGtCamera[theDDCument->theView, camera); 
Q30bject Dispose{camera); 


Listing 15 * Generating a series of images for a panoramic movie 


void MyGeneratePanoFrames(DocumentPtr theDocument) 

{ 


PicHandle 
float 
long 
Str255 


thePict; 
isiUigle; 
counter = 0; 
fName; 


GWorldPtr gw; 

GDHandle gd; 

FSSpec outSpec; 


GetGWorld{Sgw, &gd); 

SetGWorld{theDocument->theWindow, nil); 


outSpec - theDocument->theFileSpec; 
for (zAngle - 360; zAngle >0; zAngle -- 30) { 
short i; 


(continued on next pogej 
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Listing 15- GeneraHng a series of images for o panoramic movie (continued) 

MyRotateCameraY(theDocument, -30-0 *kQ3 Pi/1B 0.0); 

S etGWo r1d(t heDoc ume nt->th eWindow, nil); 

MyDrawOffScreen(theDocument); 

MyDrawOnScreen(theDocument); 

EetGWorId{theDocument*>drawContextOffScreen^ nil); 
thePict = 

OpenPicture( &theDoGumeTit->drawContextOffScreen->portHect); 

Loc kPixe1s(th eDocument» > d rawC o nt extO f f S c r ee n->p o rtPixMap); 
CopyBits ((BitMap*) 5itheDocument->drawContext0f fScreen“>portPixMap, 
(BitMap*)&theDocument“>drawContextOffSGreen->portPixMap, 
^theDocument“>drawContextOffScreen->portRect, 

& t heD oc umen t->drawC on tex tOffScreen->por tRec t, 
srcCopy, NULL); 

UnlockPixels(theDocument->drawContextOffScreen->portPixMap); 
ClosePicture(); 

... // Set up the outSpec for the next image. 

MySavePICT(thePict, fioutSpec); 

KillPicture(thePict); 


GENERATING THE INTERACTIVE PANORAMIC MOVIE 

You use the i\WW tools and scripts provided in the QuickTime VR ATS tu generate 
your interactive panoramic movie, (See die QuickTime VR ATS documentation for 
more information.) 

Stitching the images. The stitching tool, called by the Stitch76B script, joins the 
series of computer-rendered images of your panorama into a single 36(F panoramic 
PICT file, IPs also used to stitch digitized photographic images together. The 
following example shows a portion of a sdtch worksheet, with appropriate values set 
for each of the input variables. The stitching tool will use images numbered from 01 
to 12 located on the drive named J lappyMac, 

set pan I n Fo Ide r " H appy Mac t Ren de r edF r ame s: ** 

s et panOu tFoIde r ^ H appyMac:Re nde re d Fr ame s i " 

set panRotate 0 

set panX 100 

set panDX 20 

set panY 0 

set panDY 10 

export panInFolder panOutFolder panRotate panX panDX panY panDY 
Stitch768 01-12 MyPano.srcPict 

This script stitches your images into a vertically oriented, 360"^ full panorama that's 
768 pixels across by 2496 pixels high, named MyPano.srcPict. 

Dicing the image into a lineor movie. The SrcPictToMovie script calls the dicing 
tool, which compresses your PICT file and divides it into equal-sized sections called 
tiles. For example, a standard-size panorama is “diced” into 24 tiles, 1 across by 24 
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down. Since we havenincluded hot spots in our movie, our worksheet will include 
only one line, which calls the SrcPictToMovie script: 


22 devef 


SrcPictToMovie "HappyMac:RenderedFrames:MyPane•srcPict" 9 
"HappyMac:RenderedFraunes rMyPano.srcMoov" 

This script dices your 360® panoramic PICT into a standard QuickTime linear movie 
using l-by-24 tiling and the Cinepak compressor. 

Converting the linear movie to on interactive movie- The iVlakeSingleNodeMovie 
script takes the linear movie we just created and generates an interactive panoramic 
mo\de. Since we^re creating a very standard type of interactive movie, this script does 
everything we need. 

This example creates a single-node interactive panoramic movie file named 
My3DMovie: 

MakeSingleNodeMovie "MyPano,srcMooV" “My3DMovie" 


RENDERING YOUR PANORAMA DIRECTLY 

You can avoid using the stitching tool by rendering your panorama directly. However, 
since QuickDraw 3D supports rendering directly to a plane hut not to a cylinder, we 
have to approximate cylindrical rendering with a “slit” approach, using the cameras 
available to us. 

The sht approach is the equwalent of using a real [)anoramic slit camera, which spins 
around, taking very thin pictures and laying them next to each other on the film. 
WTien simulating cylindrical rendering, we do the camera work described earlier, 
hut instead of rotating 30'^ at a time and grabbing each frame, we rotate a very 
small amount each time and just grab a slit out of the middle of each frame, thus 
approximating a cylinder I'he narrower the slit width, the closer we get to a true 
cylinder. IfyouVe curious about the mathematics of slit sizes, see “Calculating the 
Optimal Slit Width.” 

In our case, the largest slit size that gives us a very small amouin of error is 32, so we 
use this number to generate our panorama (Listing 16). To try^ different sizes, simply 
put in a different number for the slit size constant, which weVe called factor. 

'The PICT file you get from this operation is oriented horizontally. However, the 
QuickTime VR tools expect the stitching tool output to be vertical, so you first 
need to rotate your PICT clockwise 90° using a PICT editor such as Photoshop or 
PhotoFlash, You then use the SrcPictToMovie and MakcSinglcNodeMovie scripts 
as described above to turn the PICT into an interactive panoramic movie. 

THE NEXT STEPS 

So far weVe made QuickTime linear object moHes and panoramic PICT files tiiat 
can be converted to interactive movies with the QuickTime VP. ATS. There are a 
number of directions you can go from here. If you have your own panoramic renderer, 
you may want to substitute it for our slit^based rendering. Or you may want to build 
a full interface to allt>w the user to place the camera and set up all the parameters 
involved in QuickTime VP moviemaking. We hope to write a future article about the 
QuickTime VP movie file formats and how to write out QuickTime VP movie files. 

QuickTime VP movies already have several diverse uses. Developers with extensive 
collections of 3D data sets can generate QuickTime V^R movies from their data sets 
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Listing 16* Rendering the panorama directly 
idefine factor 32*0 

void MyGeneratePanoMovieOirect(DocumentPtr theDocument) 
{ 


PicHandle 

thePict; 

float 

zAngle; 

short 

i? 

GWorldPtr 

gw, largeGW; 

GDHandle 

gd; 

FSSpec 

outSpec; 

Rect 

sourceRect, destRect, largeRect - {0, 0 


GetGWorId(&gw, & gd); 

S etGWo r1d(th eDo c umen t->theWindow, nil); 
outSpec = theDocuineiit->theFileSpec; 

NewGWorld(slargeGW, 32, slargeRect, nil, nil, useTempMem); 

Loc kPiX e1s(1ar geGW->po rtPixMap); 

SetGWorId(largeGW, nil); 

EraseRect(alargeRect); 

sourceRect ^ destRect = largeRect; 

sourceRect,left = 256 - factor/2.0; 

sourceRect,right = sourceRect-left t (short)factor; 

destRect.left = 0; 

destRect.right = (short)factor; 

for (zAngle = 360.0; zAngle > 0.0; zAngle -= 360.0/(2496.0/factor)) { 
MyRotateCameraY(theDocument, -2*kQ3Pi/(2496.0/factor)); 

SetGWorId(theDocument->theWindov, nil); 

MyDrawOff Screen {theDociMent); 

HyDrawOnScreen(theDocument); 

SetGWorld(largeGW, nil); 

LockPixels {theDQcijinent->dravCoiitextOf f Screen->pQrtPixMap); 

CopyBits((BitMap*)&theDocunient->drawContextOffScreen->portPixMap, 

(BitMap*)&largeGW->portPixMap, &sourceRect, ^destRect, 
srcCopy, NULL); 

U nlockPixeis(theDoc nmen t->drawC ont extO £ f S c ree n->portPixMap); 
destRect.left = destRect.left t (short)factor? 
destRect.right = deatHect.right + (short)factor; 

} 

SetGWorId(largeGW, nil)? 

thePict = OpenPicture(&largeGW->portRect); 

CopyBits((BitMap*)&largeGW->portPixMap, (BitMap*)&largeGW->portPixHap, 
&largeGW->portHect, &largeGW->portRect, srcCopy, HULL); 
ClosePicture(); 

UnlockPixels(largeGW->portPixMap); 

DisposeGWorld(largeGW); 

MySavePICT(thePict, ioutSpec); 


} 
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CALCULATING THE OPTIMAL SLIT WIDTH 


In Jhe slit approach to simulating cylindrical rendering 
for QuickTime VR panoramic movies, narrower slits 
approximate cylinders better than wider ones. In our 
calculations, the size of the error shows us the effect of 
increasingly wide silts. 

Our error is defined as the vertical distance between the 
top of our projection plane ot the maximum verticol field 
of view and the top of the cylinder weVe trying to 
approximate. We consider an error of less than 0.5 pixels 
to be acceptable. Since fractional pixels conT be drawn, 
errors greater than 0.5 will round up to be a full pixel error. 
Because this error Is so small, we can use the same field 
of view for generating both the slits and the entire frame. 

To determine the vertical error, we must first determine the 
maximum horizontal distance between the plane and the 
cylinder. This distance, labeled y, can be seen in the top 
view of our camera and cylinder, as shown in Figure 5. 
The two triangles formed are identical {except for their 
orientation). The width of our slit is 2x. 

Given that 2x is the width of the sirt, y is the distance 
between the plane and the cylinder, r is the radius of the 
cylinder, and a is the angle: 



sin a = “ a = sin 

cos a = ^ ^ a = cos^^(1 - 

Therefore, where r is the radius of the cylinder and c is 
the circumference: 

a= sin^^ (y) = cos"^ 

y= r(1-cos(sin-' {^|1) 

c[l-cos(sm~'{^))) 

2jt 

Since we know the final panorama we end up with is 2496 
pixels wide, we can use this os our circumference, and 


y= 397.25(1-cos (sin-’( 39^)11 

However, this only gives us the slit width for a given 
distance y, so we must concern ourselves next with the 
important error, the vertical error, labeled fv, A side 
view of the panorama showing this error appeors in 
Figure 6. 

fv is the distance in pixels between the pixel we see on 
the plone and the pixel we see on the cylinder for o given 
field of view. Since we already hove on equation for y in 
terms of our slit width (2x), and we know that the vertical 
field of view (FO^v) of the lens we're using is 97“ we con 
easily determine this error using the tangent equation 

7 '2 

397.25 (1-cos (sin'’ ( 39 “ ))) tan {^] 

Since we know that our FOVv Is 97° we hove 
Fv= y tan (48.5) 

which leaves us with a final equation of 

ev= 397.25 ( 1 -cos|sin-'( 3 ^^))) tan (48.5) 

The slit widths for various vertical errors are as follows: 

Vertical error (fv) Slit width (2x) 

0.14228682 20 

0.20490732 24 

0.27892462 28 

0.36434438 32 

0.461 1731 36 

0.56941818 40 

For o slit width of about 38, we hove an error of less than 
0;5. Theoretically, this should yield occurate pictures. 
Therefore, for panoramas that ore 2496 pixels wide, like 
ours, the optimal slit width is 32 (the largest factor of 
2496 that's still less than 38), 


to show to potential cQStoiners; the movies display the modeled objects more 
effectively than a 2D representation and don’t compromise the data in the process. 
Archaeologists can use QuickTime VR movies to record site information during 
digs, realtors can use them to give clients virtual tours through the property theyVe 
offering, and cities can use them to provide tourist information on kiosks. Museums 
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a - angle 
r = radius 

2x ^ wjdJh of tlie siiJ 

Y - distance between tbe plane ond the cylinder 


row/2 



fv = vertical error 

fOVv - vertical field of view 

r = radius 

y = distance between the plane ond the cylinder 


Figure 5. Determining y, the distance between the Figure 6* Determining fv, the vertical error 

plane and the cylinder 


can archive or display their collections with QuickTime VR movies. For example, 
Apple and the Asian Art Museum of San Francisco have put together a virtual 
walkthrough of one of the museum’s special exhibits; you can check it out on the 
World Wide Web at http://sfasian.applexom. Also, for the late>st information on 
QuickTime VR, see http://qrvr,qi]ickcime,apple,com. Use your imagination — the 
possibilities are endless! 


RECOMMENDED READING 

• "'QuickDraw 3D: A New Dimension for Macintosh Graphics" by Pablo Fernicola 
and Nick Thompson^ develop Issue 22. 

• "The Basics of QuickDraw 3D Geometries" by Nick Thompson and Pablo 
Fernicota, devefop Issue 23, 

• 3D Graphics Programming With QuickDraw 3D (Addison-Wesley 1995). 

• Inside Maclrtfosh: QuickTime and Inside Macintosh: QuickTime Components 
[Addison-Wesley 1993). 

• One Hundred Years of Solitude by Gabriel Garcia Marquez (Harper Row^ 
1970), This won't directly help you with QuickTime VR or QuickDraw 3D^ but it's 
Philip's favorite novel. 


Thariks to our technical reviewers Eric Chen, 
Michael Chen^ Ken Doyle, Ian Small, and Nick 


Thompson. Special thanks to Chris Flick and 
Pablo Fernicola.* 
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PRINT HINTS 

QuickDraw GX 
Breaks the 
Space Hack 


DAVE POLASCHEK 


with Roman fonts, where there are only 256 characters 
at most, but in the case of two-byte fonts such as 
Chinese, Japanese, and Korean fonts, where there can 
be tens of thousands of characters and tlie font can be 
tens of megabytes in size, sending only the required 
characters makes a big difference in speed. 

Incidentally, with QuickDraw GX you don't need a 
specialized printer to print cwo-byte fonts. It divides 
fonts wixh more than 256 characters into several 
smaller fonts witli new encodings containing just the 
characters you need, so you can print characters from 
the font on any PostScript printer. 


Before QuickDraw GX, when an application tliat 
generated its own PostScript^'^ code wanted to make sure 
the printer could print a particular font, it could send 
ojie space character in the needed font. The LaserWriter 
driver would check die printer to see if the font was 
available, and if not, the driver would send die font to 
the printer so diat it would he available to print the 
space character — and any other characters in that font 
that the application-generated PostScript code might 
require. The reason for using a space was simple: you 
didn't want to mark tlie page just to get a font to the 
printer, and a space wouldn't mark it. d'his technique, 
first described in “ITe Perils of PostScript” back in 
dnrlap Issue 1, became known as the “space hack.” 

Unfortunately, the sfiace hack doesn't work with 
QuickDraw GX. This column describes a new way tor 
applications that generate their ovn PfjstScript code to 
send Fonts to die printer. The code to do this is 
provided on this issue s C"D. 

QUICKDRAW GX CHANGES THE PICTURE 

QuickDraw GX has a really cool imaging model, 
supports all kinds of whizzy features, and to top it ofF^ 
intnKluces the long-awaited new printing architecture. 
But it has one snag: after all the years you’ve spent 
getting your PostScript printing tuned just the way you 
like it, QuickDraw GX breaks the space hack. 

The space hack depends on a font's entire character set 
being sent to die printer in response to die need for a 
single character (the space character). But QuickDraw 
CiX sends only the needed characters in a font to a 
printer, because it's trying to conserve memory on the 
printer and also because sending less data means faster 
transmission of that data. This isn’t such a liig issue 


THE NEW WAY TO DOWNLOAD FONTS 

So QuickDraw GX has lots of advantages over 
QuickDraw, but the space hack is broken. \^diat's the 
poor programmer to do? 

You can use a new font downloading method based on 
calling CJXFlattenFont, a handy function introduced 
with QuickDraw CiX, to convert the font to a form 
that’s easily sent to the printer. CiXFlattenFont is 
intended to convert any font present on your Macintosh 
into the outpiit font format of your choice. (Conversion 
is limited by the capabilities of the scalers present, as 
explained in “QuickDraw CiX Font Scalers.”) 


QUICKDRAW GX FONT SCALERS 

The QuickDraw GX Open Font Architecture accepts 
drop-in font scalers. A font scaler is a bit of code that 
takes a font of a given type ond converts it to bitmaps 
for display. It also converfs fonts to outline format and 
can optionally convert a font to another font formot. 
QuickDraw GX includes three defoult scalers: 

• the bitmap scaler^ which is essentially the same as 
in QuickDrow 

• the TrueType GX scaler^ which supports the 
TrueType GX format 

• the Type 1 scaler, which is part of Adobe^*^ Type 
Manager 

All of these default scalers are capable of generating 
bitmaps for screen display and PostScript fonts for 
printing. Only the TrueType GX scaler can generate 
downloadable TrueType fonts. 


DAVE POLASCHEK recently relocated to Colifornio to [om lived in beautiful sunny Minnesota, and wonders if hell get used to 

Apple's Developer Technical Support group. He's been told that the harsh San Frandsco Bay Area winters before he's bald and 

supporting printing leads to hair loss and insanity. Dove previously crazy, or if it's already too late.* 
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GXFlattenFont can produce Type 1 data that’s ready to 
be sent to your PostScript printer with no problem. 

Now let’s rum to the code that replaces the old space 
hack. l"he rough idea is to call GXFlattenFont on a 
QuickDraw font reference and a set of characters 
(an encoding) that you need to print, and return the 
result in a fomi that^s easy to send to the printer. For 
simplicity, if no encoding is present, we use the 
standard Macintosh encoding. Listing 1 shows a font¬ 
downloading routine, FontToPict, diat uses this 
teciinique if QuickDraw GX is installed. (This is a 
somewhat simplified versionj see the CD for the full 
code of FontToPict and its related utility functions.) 

FontToPict starts by checking to see if QuickDraw GX 
is installed. If not, it uses the old hack of printing a space; 
otherwise, it calls MakePSHandle {Listing 2), which 
calls the utility function ConvertQDFontToGXFont 
to conven the QuickDraw font reference into a 
QuickDraw GX font reference. MakePSHandle then 
checks to see if an encoding has been passed in; if not, 
it builds the standard Macintosh encoding. Next it 
calls FontToHandle, which is ju.st a wrapper for 
GXFlattenFont. GXFlattenFont converts the specified 
font to the Type 1 format. Error-handling and cleanup 


code is last. Simplicity itself! The result, whether 
QuickDraw GX is present or not, is a PICT that you 
can send to the printer by calling DrawPicture once the 
printer port has been opened. 

WTien calling MakePSHandle, you should specify an 
encoding array that contains the characters you intend 
to actually print. This prevents QuickDraw GX trom 
sending the entire font to the printer and becomes y^ry 
important when you make your application WorldScript 
aware. There’s an #ifdef in the code on the CD that 
generates only the encoding array you need in order to 
use a portion of the font. As mentioned earlier, with 
Chine.se, Japanese, and Korean fonts, sending only tlie 
characters you need can make tlie difference between 
sending a few kilobytes or many megabytes of data to 
the printer. If you don’t use tlie entire font, remember 
to encode the characters that you want to draw, 
using the same encoding that you passed in to the 
MakePSHandle function. 

You may want to have HandleSpoolProc (which is 
called by GXFlattenFont and included on the CD) 
spool directly to the printer via picture comments. This 
way you won’t need memory available to hold the font 
data at the intermediate steps. 


Listing 1. FontToPict 

PicHandle FontToPict(short qdFont, short qdStyle) 

{ 

Rect theRect = {0, 0, 1, 1}? 

PicHandle thePict = OpenPicttire {stheRect); 
const short kPostScriptHandle = 192; 

if (GXInstalled()) { //If QuickDraw GX is installed, use the new method. 

Handle piccommentHdl; 

unsigned short *inyEncoding = nil; 

MakePSHandle (qdFont, qdStyle, ntyEncoding, SpiccommentHdl); 

PicCoitiment (kPostScriptHandle, GetHandleSize (piccommentHdl), piccommentHdl); 

} else { //If QuickDraw GX isn't installed, use the old method. 

Point PenPoint; 

//We would normally set the clip here, but since we're just drawing a space there's no need. 
GetPen(spenPoint); // Save the pen location, 

TextFont(qdFont); 

TextFace(qdStyle); 

DrawChar(' *); 

MoveTo{PenPoint.h, penPoint.v); // Restore the pen location. 

> 

ClosePicture(); 
return (thePict); 
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Listing 2, MakePSHandle 

OSErr MakePSHandle(short qdFonti char gdStyle, unsigned short *encodingArray, Handle *outputHandle) 

{ 

OSErr status = noErr; 

gxFont theFont; 

unsigned short *myEncoding; 

Boolean madeEncoding = false; 

theFont “ ConvertQDFontToGXFont(qdFont, qdStyle); // Convert to a QuickDraw GX font reference, 

// If no encoding, create the standard Macintosh encoding* 
if ((encodingArray) { 
long returnLength; 

myEncoding = (unsigned short *}NewPtrClear{256 * sizeof(short)); 
returnLength = MakeMacBflitEncoding(theFont, myEncoding); 
if (returnLength 1= 256) { 

DebugStr("\pHmm, We didn’t get a full encoding*”); 
return (returnLength); // Pass the error along. 

} 

madeEncoding = true; 

> else { 

myEncoding = encodingArray; 

> 

*outputHandle = FontToHandle[theFont, myEncoding); 
if (madeEncoding) DisposePtr((Ptr)myEncoding); 

status = HemError(); 
if (status == noErr) { 

status = GXGetGraphicsError(nll); 
if (status 1= noErr) { 

DisposeHandle{*outputHandle); 

*outputHandle = nil; 

} 

y 

return (status); 


DOWNLOADING HAPPINESS 

^rhe new font dow^nloading method takes a little more 
work but produces better results in your printer font 
handling. You can easily send needed fonts to the 
printer, either the whole font or only the characters 
you1l be using* As a side benefi t, you get support for 
two-byte font systems without having to write custom 


code for handling the large fonts or, worse yet, having 
to depend on the fonts being installed on the printer in 
a specific manner* Even if you’re not ready to add 
QuickDraw GX imaging to your application today, 
adding QuickDraw GX compatibility improves the 
printing experience for your customers. 


Thanks Jo Oar\ Upton for providing Jhe idea and core code Alexander, Dove Hersey, end Don Upton for reviewing this 

illustrating the new fonl downloading method, and to Pete '"Luke" column.* 
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FIkker-Free Drawing With QuickDraw GX 


Does your QuickDraw GX applkatmi have a look reminiscent of the 
old silent movies? If so, it sujfers from flicker. But don V despair — help 
is as near as this issuers CD, whereyotdll fnd a ready-to-use librmjfor 
doing 7nem.ory-efficient, flicker-free drawing inside a window. This 
article explores the pi'ohlem. of flicker and its solutions and walks you 
through the code. 



HUGO M. AYALA 


My first encounter with the idea of flicker-free drawing happened when I was a 
12-year-old kid reading my father's copy of Nlbbk\ a journal about programming the 
Apple IL A review of new products mentioned a program that had impeccable 
animation and guessed that the programmer was most likely using “page switching” 
to produce flicker-free drawing* Page switching (or page flipping) took advantage of 
the fact tliat the Apple II could use more than one location in memory (more than 
one page) to hold the screen image* Given enough memory^ a programmer could set 
things up no that there was a second “offscreen” page to draw into while the first was 
being shown on the screen. Switching back and forth between these two pages made 
flicker-free drawing possible. 

Today's hardw^are bears little resemblance to the Apple ll, hut the technique for doing 
flicker^ffee drawing is essentially the same* It involves double bujfefing (also known as 
screen bnffaing) — causing all objects to be drawn first into an offscreen buffer and 
then copying that entire buffer to the front buffer (the window). Both this and the 
Apple II method eliminate the need to erase the old position of a moving image 
directly on the screen before drawing its new position, which is the primary cause of 
flicker. 


The librar}^ that accompanies this article manages an offscreen buffer for a 
QuickDraw GX view port* Using it will enable you to give your QuickDraw GX 
application a more professional feel by removing flicker. You could use the offscreen 
library provided with QuickDraw GX to do screen buffermg, but because it's a iivuch 
more general-purpose tool, you would have to liandle most of the minutiae of 
examining screen devices, filling out the bitmap data structures, and allocating and 


HUGO M, AYAIA (hugo@mit.edu, http;// 
web.mlLedu/hugo/www) spent five years 
working on QuickDraw GX as □ deveiopmenl 
engineer at Apple before returning to MIT to 
pursue a Ph.D. in rrechontca] engineering. His 
current research interest is how to design the 
undercorriage of large earth-moving equipment 
so that it doesn't get thrashed so fast by rocks and 
dirt. To pay for the Ph.D., he moonlights doing 


computer graphics work, which has been his 
hobby since he was o lad. After finishing his 
Ph.D., Hugo plans to branch off into drawing 
comic strips, like the one thot he's been drawing 
for his school newspaper. If you ever try to give 
Hugo directions, you need to know that he's 
directionolly challenged — he reolly can't tel! his 
left from his right.* 
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releasing the memory yourself. The library provided on this issuers CD does all of 
that for you. 

I’ll walk you through the library code, illustrated by the sample application called 
Flicker Free on the CD, but first FU give some background on the problem of flicker 
and its solutions. This article assumes that you already know a thing or two about 
QuickDraw GX; if you don’t, see die article “Getting Started With QuickDraw GX’^ 
in develop Issue 15. The essential references are Imide Macintosh: QuickDr^ GX 
Directs and Inside Macintosh: QttickDf^aw GX Graphics. 

FLICKER — ITS CAUSES AND SOLUTIONS 

For a dramatic illustration of flicker, run the sample application Flicker Free (you’ll 
need a color Macintosh with QuickDraw GX installed). You’ll see a window filled 
with fifty circles bouncing around in different directions (see Figure 1). 



Fi9ure 1. The startup screen from the sample application Flicker Free 


The Drawing menu in the Flicker Free application offers a choice of buffering 
methods; full screen buffering, no screen buffering, and half and half. The program 
starts up in half-and-half mode: the left side of the window (the side with the Apple 
menu, for those like me who can’t tell left from right) is being buffered, while die 
other side isn’t. Switch among the buffering choices to get a sense of the difference 
that flicker or its absence makes in how you experience the animation. 

What causes flicker? In our case, the shapes on the right are being erased and then 
redrawn over and over again as they move across the screen. And although the 
rendering of the shapes is very fast (your mileage may vary according to CPU speed), 
the act of constantly drawing and erasing them makes the whole thing look like an 
old silent movie. In places where circles overlap, pixels are made to take on different 
colors as each shape is drawn. In the resulting blur of colors, it’s hard to see which 
shape is in front. 
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The key to avoiding flicker is to avoid erasing pixels on the screen needlessly between 
two stages of a drawing and to change only the color of those pixels that need to 
change, d'he left side of our sample application window is being double buffered, 
meaning that each circle is drawn into an offecreen buffer and then the whole scene is 
transferred onto the screen* Because at each step in the animation only the pixels that 
need to change color do, the movement of tlie circles is rendered flicker free. With 
double buffering there’s no problem telling which circles are in front. Shapes move 
neatly past each other. 

Figure 2 shows two frame-by-frame drawing sequences illustrating the difference 
between an update frill of flicker and a flicker-free update. 


Update with flicker 



1 2 3 4 5 6 


Flicker-free update 



1 2 3 4 5 6 


Figure 2. An update full of flicker vs. a flicker-free update 

The upper set of frames in Figure 2 shows what happens without double buffering. 
The screen is erased (in frame 2 and then again, out of view, in frame 7) and then 
each circle is added to the screen in its new position* The whole assembly of circles 
appears on the screen only briefly before they’re erased and the process is started 
again. The lower set of frames in the figure shows the update process during double 
buffering* The offscreen image is transferred to the screen in a sw^eep replacing the 
previous image* You can see the sweep line as a very subtle horizontal break in the 
frame. 

The sample application gives a dramatic demanstration of how^ flicker affects 
animation. But even if your QuickDraw GX application isn’t an animation package, 
it probably suffers from some form of flicker when update events are serviced* The 
most common and most annoying flicker occurs when applications engage in some 
form of user interaction — for example, dragging marquees, manipulating shapes, 
and editing text. 

BUFFERING TRADEOFFS 

When you’re considering using screen buffering, it’s important to understand the 
tradeoff with drawing speed* In the sample application, the speed at which the circles 
travel is a function of die number of circles in die window, the size of die window, 
and your choice of screen buffering* G iven the same window size and number of 
shapes, draiving whh screen buffering is always slower tha?i with no sa^een Imffhing. Screen 
buffering involves the same amount of work as screen drawing plus the additional 
step of transferring the offscreen image onto the screen. 
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Wlien the window contains one circle, the unbuffered performance is at least three 
times faster than that of the buffered case (again, your mileage may vary depending 
on your CPU speed). As more shapes are added, the perfonnance in both cases 
goes down, but so does the performance gap between the two: the unbuffered 
performance doesn*t have as much of an advantage over the buffered perfonnance. 
This is because the speed at which the offscreen buffer is transferred to the screen is 
independent of the complexity of the shape it contains; it’s purely a function of its 
size. As the complexity of the shape being buffered increases, the relative cost of 
shape buffering decreases. 

Now, this doesn’t mean that you should buffer only complex shapes that take a 
long time to draw. What it means is that when you add screen buffering to your 
application, you have to be mindful of what constitutes a reasonable tradeoff between 
buffering and drawing performance. You should try diings out and see if screen 
buffering is the tcchnitjue best suited to your needs. Alternatives to screen buffering 
that enable flicker-free drawing include the use of transfer modes and geometric 
operations, 1 hope to discuss these in a future devdop article. 

Meanwhile, well take a look at the screen buffering library that accompanies this 
article, which is ready for you tt> incorporate into your QuickDraw GX application, 

1 wrote the library with perfonnance issues in mind. Thus, it takes advantage of the 
fact that in the QuickDraw GX graphics object model, information that’s needed to 
render a shape can be computed once, stored in a drawing cache, and reused every 
rime that shape is drawn. The library is very careful to check before making calls 
that invalidate drawing caches, so the overheail of offscreen drawing is kept to a 
mini mum. 

A LOOK AT THE SCREEN BUFFERING LIBRARY 

Ever)^thing you need in order to use the screen buffering library is defined in the 
interface file. The libraiy consists of four major routines: the routine that creates the 
\^ew port iiuffer object, tlie one that disposes of it, the one that updates it, and the 
one that uses it to actually buffer screen drawing. The four corresponding calls 
should parallel the drawing loop inside your application. 

'The include file defines only one data t)^e: 

typedef struct viewPortBufferRecord **viewPortBuffer; 

The internals of the data type are private to the ^‘screen buFfering.c” file and are as 
follows: 

struct viewPortBufferRecord { 


gxViewGroup 

group; 

/* 

The offscreen's view group* */ 

gxViewDevice 

device; 

/* 

The offscreen's view device. */ 

gxViewport 

view; 

/* 

The offscreen's view port, */ 

gxShape 

buffer; 

/* 

The bitmap of the offscreen's view device. */ 

gxBittnap 

bits; 

/* 

Source structure for the buffer shape. */ 

Handle 

storage; 

/* 

A temp handle to the bits of the bitmap. */ 

gxTransfom 

offxform; 

/* 

This draws into the offscreen. */ 

gxTransfomt 

on_xform; 

/* 

This draws onscreen, */ 

gxShape 

eraser; 

/* 

Erases offscreen to background color. */ 

gxShape 

marker; 

/* 

Used to draw into the offscreen. */ 

gxShape 

updatearea; 

/* 

Represents the area to update. */ 
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short 

usehalftone; 

/* 

True if screen has a halftone. */ 

WindowPtr 

window; 

/* 

The 

window of the view port, */ 

gxViewPort 

parent ? 

/* 

The 

parent's view port, */ 

gxViewPort 

screenview; 

h 

The 

view port to buffer. */ 

gxShape 

page; 

/* 

The 

shape that we're asked to draw. */ 

gxRectangle 

bounds; 

/* 

The 

offscreen's bounds. */ 

gxMapping 

invmap; 

/* 

The 

inv offscreen view port map. */ 

gxPoint 

viewdelta; 

/* 

The 

last delta for the offscreen, */ 


>; 

typedef struct viewPortBufferRecord viewPortBufferRecord; 

You don't need to understand a[l of the fields in the viewPortBufferRecord data 
structure to use the library. However, if you start having prolilenis gettijig things to 
work inside your application and find that you need to modify the screen buffering 
library, see **'rhe viewPortBufferRecord Data Structure” for some additional helpfid 
information. 

In general terms, the code works by allocating a number of QuickDraw GX objects 
and reusing them as required. Memory for the offscreen buffer is allocated froni the 
MultiFinder temporary memory heap flemp Mem). Allocation of the storage block 
is postponed until the last possible moment, and die block is kept locked and 
nonpurgeable only during the drawing opera don. That is, after the resulting image 
has been transferred to the screen, the block is unlocked and marked purgeable but 
not disposed of. lliis peniiits the same block to be reused in case the memory for the 
buffer isn’t purged. 

While most users will keep their windows entirely within the btjunds of one screen, 
it’s important to handle the case where a window^ spans more than one tlevice. Each 
time the DrawShapeBuffered routine is called (as described later), the code w^alks the 
device list checking to see if the area that needs to be buffered intersects a given 
screen. If it does, the code creates a buffer with the right settings and draws into that 
device. The process is repeated for each screen. 

CREATING AN OFFSCREEN BUFFER 

You’ll need one view port buffer lor each window in your program, do create a view 
port buffer, use the NewView PortWBuffer routine. 

viewportBuffer NewViewPortWBuffer{Window?tr window, gxViewPort view, 

const gxColor *backgroundColor)? 

Look at the Initialize routine in the file “flicker ffec.c” for an example of how to use 
New\fiewd^ort\\'^offer. Here’s a description of the parameters: 

window The window that the buffering code should draw into. 

view The view port created by your application to draw into the 

given window. Note that this is different from the object 
obtained by calling GXNewWindowViewPort, in that this view 
port should have tiie window view port set to be its parent. 

baekgroundColor A pointer to a gxColor data structure indicating which color 
should be drawn to erase the offscreen buffer. Passing nil is 
equivalent to specifying white as the backgroimd color. 


FUCKtR-FREE DRAWING WITH QUICKDRAW OX 


33 




THE VIEWPORTBUFFERRECORD DATA STRUCTURE 


The following is an accounting of all of the fields of the 

viewPortBufferRecord data structure* 

• group, device, view — These are the three elements of 
an offscreen drawing environment in QuickDraw GX* 
We need one of each to drow offscreen* 

• buffer, bits, storage — These objects represent the 
bits of the offscreen device in decreasing order of 
abstraction. The field buffer is a bitmap shape that 
represents the "screen^' of the view device. The field 
bits parallels the contents of buffer and is used to 
keep information about the offscreen bitmap around 
between invocations of DrawShapeBuffered, the 
routine that draws the buffered shape. Finally, the 
storage field is the handle in Temp Mem (the 
MultiFinder temporary memory heap) that contains 
the offscreen data. 

• offxform, on_xform These are QuickDraw GX 
transform objects, offxform has a view port list that 
contains just the view port for the offscreen device. 
on_xform has a view port list for the parent of the view 
port thaKs being buffered. You may expect that the view 
port list would be the view port being buffered and not 
its parent, but when drawing onscreen weVe alreody 
taken into account all of the tronsformation and clips of 
the view port weVe buffering, and we just need to 
copy the end result to the screen. This is why we use 
the view port's parent and not the view port proper. 

• eraser, marker — These ore the auxiliary shapes used 
to erase the offscreen buffer ond to draw the incoming 
shapes. The shape eraser is of type gxFullType (a "full" 
shope) and is the color of the bockground. The marker 
(so nomed to complement eraser) is a picture shape 
that will be used to drow into the offscreen buffer. The 
reason for using the marker rather then swopping in 
the transform of the incoming shape to be offxform 
(thereby causing the shape to draw offscreen) is that 
the swapping operation would invalidate the caches 


for the incoming shape. Instead we use the property of 
picture shapes of redirecting any drawing to their view 
port list instead of the shape's own in order to cause 
incoming shapes to render offscreen. Furthermore, if 
the incoming shape is the same for every invocation of 
DfowSh ape Buffered, we can test for it and not change 
the contents of the marker. 

• updatearea — This is a rectangle shape used to 
compute the size of the offscreen buffer that is to be 
generated and what devices it falls on. 

• usehalftone — This is a Boolean indicoting whether to 
use a halftone in the offscreen buffer. 

• window, parent, screenview, page — These fields 
hold incoming parameters to the library. The window 
Field is the window in which drawing will occur. The 
porent field is a cache for the parent of the view port 
being buFered (see page 7-18 of /nsfde Modnfosh: 
QuickDraw GX Objects to learn more about view port 
hierarchies). The screenview field indicates the view 
port that will be buffered. The page field is a reference 
to the lost shape passed to DrowS hope Buffered. 

• bounds — This field indicates the visible area of the 
screenview in the coordinate space of that view port. 

• inymop — This is a mapping for translating between 
the coordinate system of the shapes being drawn in 
the window and the space of the window itseii If your 
view is zoomed in at 2x mognification, this mapping 
will be at 1/2 scale. 

• viewdelta — This is the position of the upper left corner 
of the area being buffered, in the local coordinate 
system of the window. This parameter is used to adjust 
the drawing in the offscreen buffer so that only the 
correct part of the shape being buffered is drown, and 
to position the content of the offscreen buffer when it's 
being transferred onto the screen. 


Let’s look at what it takes to create an offscreen buffer m the New View Port WBuffer 
routine (Listing I). In QuickDraw^ GX, the place wLere draw'ing occurs (for example, 
the screen or an offscreen buffer) is described by a view^ device, so the primary 
purpose of the routine is to create a view device and store it in the device Geld of the 
viewPortBufferRecord data structure. Because we want the offscreen device that we 
specify to be as close as possible to the one into w'hich we will eventuaily be drawing, 
you might think that we would go ahead and set all of the attributes of the view 
device now. But in Fact, all that we want to concern ourselves wath right now^ is 
allocating the gxViewDevice object. Later, w'hen w^e get to die drawing part, well 
check the screen and our oflscreen device and update the gxViewDerice object 
accordingly. 
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Listing 1. NewVEewPortWBuffer 

viewportBuffer NewViewPortWBuffer(WiridowPtr window, gxViewPort view, 
const gxColor *backgronndColDr) 

{ 

Handle sbHdl; 

if (sbHdl = NewHandleClear{aizeof(viewPortBufferRecord))) { 
gxink background; 

gxHalftone halftone; 

viewPortBufferRecord *sbPtr; 

HLock(sbHdl); 

sbPtr = * (viewPortBufferRecord sbHdl? 
sbPtr->window = window; 
sbPtr->screenview = view; 
sbPtr->parent = GXGetViewPortParent(view); 

We don^t allocate storage until we need it. */ 
sbPtr“>storage = nil; 

3bPtr->buf fer = GXNewShape(gxBitmapType); 
sbPtr“>group “ GXNewViewGroup(); 
sbPtr->view - GXNewViewPort[sbPtr->group}? 

sbPtr->device - GXNewViewDevice(sbPtr->group, sbPtr“>buffer); 
if (sbPtr*>usehalftone - GXGetViewPortHalftone(view, ^halftone)) 
GXSetViewPortHalftone(sbPtr->view, &halftone); 
sbPtr->offxforni == GXNewTransfonn(); 

GXSetTransformViewPorts(sbPtr->offxform, 1, &sbPtr->view); 
sbPtr->on__xform = GXNewTranaformf); 

GXSetTransfonnViewPorts(sbPtr->on_xform, 1, &sbPtr->parent); 

background = GX!^ewInk(); 
if {backgroundColor) 

GXSetlnkColor(background, backgroundColor)? 
else { 

gxColor backcolor? 

backcolor*space - gxRGBSpace? 
backcolor,profile = nil; 
backcolor.element.rgb.red - 

backcolor.element.rgb,green = 
backcolor.element.rgb,blue = OxFFFF; 

GXSetlnkColor(background, ^backcolor); 

} 

sbPtr->eraser “ GXHewShape[gxFullType); 

GXSetShapeInk(sbPtr*>eraser, background}? 

GXDisposeInk(background); 

/* The initial bounds for the offscreen is the entire window. */ 
sbPtr->bounds.left = ff(window->portRect.left); 
sbPtr->bounds.top - ff(window->portRect.top); 
sbPtr->bounds.right = ff(windoW“>portRect.right)? 
sbPtr->bounds.bottom - ff(window->portRect.bottom); 

(continued on next page) 
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Listing 1. NewViewPorfWBuffer {conYmoed} 

sbPtr->updatearea = GXNewRectangle(&sbPtr->bounds); 
GXSetShapeViewpQrts(sbPtr->updatearea, 1, & sbPtr->parent); 
sbPtr->iiiarker = GXHewShape( gxPictureType); 

GXSetShapeTransfonn(sbPtr->eraser, sbPtr->offxform)j 
GXSetShapeTrans fonn ( 3 bPtr->iMrker, sbPtr->of fxform) j 
GXSetShapeTrans fom(sbPtr->buf fer, sbPtr->on_xform); 

ResetMapping[&sbPtr->invmap); 

/* The rest of the fields in the block are initialized to 0 */ 

/* by the "Clear" in the NewHandleClear need to allocate this */ 
/* block. */ 

HUnlock(sbHdl); 

} 

return ((viewPortBuffer) sbHdl)? 


To create a vitw device we need a view group and a bitmap. Iwentually well want to 
fill in all of the values of the ^Bitmap object to match the screen, hut for now^ die 
default values assigned to the bitmap by calling GXNew'Shape are sufficient. 

d'he New View PorrVVBnffer routine also allocates a number of auxiliary objects that 
will be needed during the operation of the offscreen buffer These include the 
folltnvi ng; 

• a gxShape object to be used to erase the offscreen Iruffer 

• a pair of gxdransform objects to direct drawing of inctmiing shapes 
to the offscreen buffer and of the content of the offscreen buffer to 
the screen 

Because we'll use these ol>jects throughout the life of the offscreen buffer, well do 
best by allocating them now and releasing them at the end. Whenever possit>le, 
you'll want to allocate objects that you'll use throughout the life of your application 
up front, work with them by changing their attributes, and dispose of them at die 
end, 

DISPOSING OF THE BUFFER 

When youVe finished using the window and want to deallocate the memory being 
used by the view port buffer, you should call DisposeViewPortWlkdTer 

void DisposeViewPortWBuffer(viewPortBuffer sb)? 

sb The object previously returned from NewView PortWBuffen 

As shown in Listing 2, DisposeViewPortWBuffer just runs through the 
viewPortBufferRecord data structure and disposes of all of the objects allocated 
by NewViewPortWBuffer. 

UPDATING THE BUFFER 

V\1ien some aspect of the window in winch yoiiVe drawing changes, you need to call 
UpdateVewPortWBuft’en In particular, if you change the clip shape or the mapping 
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Listing 2. DisposeViewPor^WBuffer 

void DisposeViewPortWBuffer(viewPortBuffer sb) 

{ 

viewportBufferRecord *sbPtr? 

HLock((Handle) sb); 
sbPtr = *sb; 

/* We need to dispose of all of the things that we allocated* */ 
GXDisposeShape (BbPtr“>inarker); 

GXDisposeShape{sbPtr->eraser); 

GXDisposeTransform( sbPtr->on_xfom); 

GXDisposeTransform( sbPtr-“>of fxfom); 

GXDisposeViewDevice{sbPtr->device}; 

GXDisposeViewPort(sbPtr->view); 

GXDisposeViewGroup(sbPtr*>group); 

GXDisposeShape(sbPtr->buffer); 

if (sbPtr->storage) DisposeHandle(sbPtr->storage); 

HUnlock((Handle) sb); 

DisposeSandle((Handle) sb); 


of the viewport object that you originally passed to NewViewPortWBuffer^ you need 
to call UpdateViewPortWBuffen lyf>ically, yotf II need to change the dip shape of 
the view port to keep QuickDraw GX from drawing shapes over the scroll bar area, 
and you'll need to change the mapping in order to zoom in or scroll. 

void UpdateViewPortWBuffer(viewPortBuffer sb, gxShape clip, 

g xMapping * disp1aymap); 

sb The object previously returned from NewViewTortWBuffer, 

clip The clip shape that should he applied when dniwing into the 

window previously passed to NewVjewPortU^Biiffen Passing nil 
leaves the current clip shape untouched, "Phe initial setting is for 
drawing to occur in the entire contents of the window {including 
the area typically assigned to scroll bars). 

displ aymap The parameter used to update the view port l>uffer if you change the 
mapping of your window view port in order to zoom in or scroll If 
nil, the current mapping is left untouched. The initial setting is die 
identity mapping. 

DRAWING ON THE SCREEN 

Now we get to the real substance of the library-— the buffering routine and its 
supporting code. 

V\Tien you want to draw on die screen, youll call Draw-Shape Buffered instead of 
GXDrawShape, If the memory is available to double buffer your drawing, 
DrawShapcBufferecl will result in a flicker-free update; odierwise the routine will 
simply call GXDrawShape, 
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void DrawShapeBuffered(viewfortBuffer 3b, gxShape page, 
const gxRectangle *updatebciUiids); 

sb The object previously returned frfun New\^ewPortWT^utfer. 

page "fhe shape tliat you want to draw inside the window. This is typically 

a QuickDraw GX picture shape into which all of the shapes tliat 
make up a document have been collected. 

updateboLinds A pointer to a QuickDraw^ GX rectangle indicating wdiat area of die 
document is to Ije updated. The location of the rectangle is given in 
the coordinate system of die window’s portRect. If nil, die code draws 
the area inside the clip shape passed to UpdatcViewPortWBuften 

As shown in Listing 3, the first thing diat the buffering routine does is to compute 
die global bounds of the view port that’s being buffered. Optionally, you could specify 
wliat area inside the view port you want to have buffered. Otherwise die rourine 
attempts to draw all of the view port that’s visible on the screen. 


Listing 3, DrawShapeBuffered 

void DrawShapeBuffered(viewPortBuffer sb, gxShape page, 
const gxRectangle *updatebounds) 

{ 

viewPortBufferRecord *sbPtr; 
gxRectangle bounds; 

HLog1c( (Handle) sb}; 
sbPtr = *sb; 

if (updatebounds) { 
gxMapping map; 

GXGetViewPortMapping {sbPtr->SGreenview, fentap); 

bounds = *updatebounds; 

bounds*left = bounds.left & OxFFFFOOOO; 

bounds.right = (bounds.right + OxFFFF) & OxFFFFOOOO; 

bounds.top = bounds.top OxFFFFOOOO; 

bounds. bottom = (bounds .bottom + OxFFFF) St OxFFFFOOOO; 

MapPoints(&map, 2, (gxPoint *) abounds); 

bounds.left = bounds.left & OxFFFFOOOO; 

bounds.right = (bounds.right + OxFFFF) & OxFFFFOOOO; 

bounds.top = bounds.top & OxFFFFOOOO; 

bounds.bottom = (bounds.bottom + OxFFFF) ^ OxFFFFOOOO; 

/* We remove the fractional part BEFORE the call to MapPoints */ 

/* because we're rounding to enclose all pixels intersected */ 
y* by the rectangle. Pixels are integers. Coordinates are */ 

/* fractional. */ 

} 

else 

bounds = BbPtr->boonds; 

(confmued on next pagej 
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Listing 3. DrawS hope Buffered (continued) 


/* The above given bounds is in the window space — just right, */ 
GXSetRectangle(sbPtr->updatearea, abounds); 


/* Check to see that the shape is actually visible on the screen */ 
/* and then proceed to draw. */ 

if (bounds.left < bounds.right bounds, top < bounds .bottom) { 
GDHandle screen; 

if (sbPtr->page 1= page) { 

GXSetPicture(sbPtr->marJter, 1, &page^ nil, nil, nil); 
sbPtr->page = page; 

} 

if (screen = GetCeviceList()) { 
do { 

gxViewDevice device " GXGetGDeviceViewDevice(screen); 

/* Note that we reuse the bounds in here. 

if (GXGetShapeDeviceBounds(sbPtr->updatearea, sbPtr->parent, 
device^ Abounds)) 

BufferDrawing(sbPtr, Abounds, device); 

} while (screen - GetNextDevice(screen)); 

} 

} 

} 


If you haven’t caught on to the fact that you can connect multiple screens to your 
Macintosh, the last part may be a little confusing- Once the routine has figured the 
global bounds of the visible part of the view port that it’s buffering, it walks the device 
list checking to see if those Ijcmnds intersect each of the devices connected to the 
CPU and then calls the routine that perfonns the drawing (BufferDrawing, shown in 
Listing 4). Since most of the time a window will be completely contained within one 
screen, the BufferDrawing routine will he called only once per invocation of 
DrawShapeBuffered. Hie nice thing about lireaking up the code this way is diat die 
BufferDrawing routine can assume that it’s drawing to a single device and therefore 
it’s safe to make assumptions about the device’s capabilities. 

This approach of walking the device list is preferred to maintaining a buffer for each 
screen and having a routine to update the buffer list every time a window is moved. 
The latter approach would result in only minor performance improvements, and only 
when the window intersected more than one device. Since this is a rare case, the 
additional housekeeping isn’t worth the trouble. 

The key to imderstanding DrawShapeBuffered is the equivalence between the 
QuickDraw data type GDHandle and a QuickDraw GX view device. To walk the 
device list, the code uses the QuickDraw routines GetDeviceList and GetNextDevice. 
The GXGetShapeDeviceBounds routine converts a GDHandle to a view device. 
From the view device we can find out which area of the screen intersects the area that 
we’re being asked to update. 


The Displciy Manager can help you walk the device list, as discussed in the 
Grophicol Truffles column in this issue of devehp* 
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Listing 4. Buffer Drawing 


static void BtifferDrawing(viewPortBufferRecord *sbPtr, 

const gxRectangle ’•^boundsPtr^ gxViewDevice target) 


gxRectangle 

long 

gxMapping 

gxShape 

gxBitmap 

OSErr 

gxPoint 

gxBitmap 


bounds = *boundsPtr; 

depth, size, gxstatus; 

map, savemap; 

devsh; 

devbits ? 

status; 

vievloc ; 

oldbits = sbPtr->bits; 


/* Fill in all the values of abPtr->bits. */ 


viewloc*x = bounds•left; /* These numbers are already in */ 
viewloc^y = bounds*top; local space* */ 

/* Compute the onscreen location of the buffer* */ 


/* This is the important part, allocating the actual bits* */ 
size ^ sbPtr->bits.rowBytes * BbPtr->bits.height; 
check(size > 0); 
if (sbPtr->storage) { 

if ((* {sbPtr->stora 9 e)) t- nil) 

SetHandleSixe(sbPtr->storage, size); 
else { 

EeallocHandle(sbPtr->storage, size); 

nrequire(status = HeniError{), TempflufferFailed); 

} 

} 

else 

require{sbPtr->storage - TempNewHandle(size, ^status), 
TempBufferFailed); 

HNoPurge(sbPtr->storage); 

HLock(5bPtr->storage); 

sbPtr->bits.image = * ((void **} sbPtr->storage); 


/* See if we need to invalidate all of the world when we do this* */ 
if (oldbits.image 1= sbPtr->bits*image j | 
oldbits.width J= sbPtr->bits.width || 
oldbits.height 1= sbPtr->bits.height || 
oldbits*rowBytes 1= 3bPtr->bitS.rowBytes || 
oldbits.pixelSize 1= sbPtr->bits.pixelsize || 
oldbits.space 1= sbPtr->bits.space \\ 

(oldbits.set J= sbPtr->bits.set && oldbits.set && 
GXEqualColorSet(oldbits*set, sbPtr->bits.Bet) == false) || 
(oldbits.profile 1= ebPtr->bits.proflie oldbits.profile && 
GXEqualColorProfile(oldbits.profile, sbPtr->bits.profile) 

== false)) { 
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Listing 4- BufferDrawing {continued} 

GXSetBitmap(sbPtr“>buffer, SsbPtr->bitSf nil); 
GXSetViewDeviceBitniap{sbPtr->device, sbPtr“>buffer ); 

} 

else { /* We test this one instead */ 

sbPtr->bits.set = oldbits.set; /* of the disposed one* */ 
sbPtr->bits.profile - oldbits.profile; /* Ditto */ 


/* Erase the offscreen bitmap^ draw the shape into it, and then */ 
/* copy it onscreen- */ 

GXBrawShape(sbPtr->eraser j; /* Erase, */ 

GXDrawShape{sbPtr->marker); /* Buffer. */ 

GXDravShape{sbPtr->buffer); /* Transfer ** done. */ 

HUnlock(sbPtr->storage); 

HPurge(sbPtr->storage); 
if (devsh) 

GXDisposeShape(devsh); 

GXGetGraphicsError(&gxstatns J; 
ncheck(gxstatus); 
if (gxstatus) 

goto DrawingFailedj 
return; 


/* Dispose of the device bitmap. */ 


TempBufferFailed s 

GXDisposeShape(devsh); /* Dispose of the device bitmap. */ 

DrawingFailed: 

GXD raws h ape(s bPt r“>upd at e area); 

GXDrawShape (sbPtr-->page) ? 


In BufferDrawing, all of the parameters needed to create an ofifecreen bitmap as 
required by the given device are finally computed. Note that in die BufferDrawing 
routine there are no calls diat create new objects; there are only calls that modify 
objects that were created when NewMewPortW^uffer w'as called. I'he modifications 
are done only if needed. Ftjr example, before calling GXSetTransfomiMapping, 
the library checks to see if the mapping has changed and merits updating. Without 
this check, the transform cache would be needlessly invalidated some of the time. 
Sirnilariy, the code checks to see if any of die parameters of the bitmap for the 
offscreen view device have changed before calling GXSetBitmap and 
GXSetViewDeviceBitniap. 

Changing the bitmap for the view device is one of the most expensive operations in 
QuickDraw GX because it invalidates most of the drawing caches. Fortunately, the 
check to see if the bitmap needs to be updated executes very quickly in spite of its 
length, and the cost of rebuilding all of the shape caches is avoided if possible. 

The most con basing thing in the BufferDrawing routine is the call to the 
GXGetOeviceBitmap routine (omitted from Listing 4; see the full code on the CD 
for details) and the subsequent call to GXDisposeShape for the same object. This 
routine obtains a copy of the read-only object in QuickDraw^ GX that represents the 
bitmap for a given screen. There are two important points about this. The first is that 
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since we^re being given a copy and not the object itself, we have to dispose of the 
object after weVe finished with it. You may think that it would be more efficient to 
get the object during the mitializarion routine and then dispose of it when weVe all 
done* But that's the other important point. Since the object that we have is a copy of 
the original, our copy would not be updated if the depth of die monitor was changed 
or the color table for the device had been updated. As a result of these two points, 
w'e're forced to allocate an object every time through our drawing loop, something 
that should be avoided in general. 

THE REST OF THE ROUTINES 

The rest of the routines in the offscreen buffering library provide support and access 
to some of the internal fields of the view P or tBuffer Record data structure. If you need 
more information on how to use these, look at the sample code included on this 
issue’s CD. 

ril mention one odier routine here. Because the internal view port created by the 
library is inaccessible from the outside, the routine SetViewd^ortWBufferDidler is 
provided to change the dither level of die view port. If you need to change other 
attributes of the offscreen view^ piirt, use the SetViewPortWBufferDither routine as 
a template. 

void SetViewPortWBufferDither(viewPortBuffer sbi const long ditherlevel)? 
sb The object previously returned from NewV^iewPortA\T3uffcr. 

ditherlevel The dithering level to set the offscreen view port to, 

THINGS TO TRY IN THE CODE 

If the code presented so far doesn’t meet your particular needs, you may want to try 
changing or fine tuning it. I lere are some soggestions anti observations about things 
that you may want to try. 

BITMAP ALLOCATION 

Currently the code looks for memory in the MultiFinder temjiorary memory^ heap 
( lemp Mem) and will hack down in case it can't olitain the memory for the offscreen 
buflen If you need to guarantee that your drawing will be screen buffered, you1l need 
to change the memory allocation code inside the BufferDrawing routine, 

INTEGRATED ERROR HANDLING 

There are two places where memory allocation can trip the screen buffering library. 

If the lihraiy fails to allocate enough memory to hold its data sti’uetures, it will return 
nil from NewView Pc>rtWBii lTer, You may need to change this to better fit in %vith 
your application’s error model. 

The library will handle a failure to allocate the offscreen bitmap by resorting to 
drawing with GXDrawShape, If you want something different, see “Bimiap 
.Allocation” above, 

DEEP POCKETS 

If the original data that you'd lie working with requires more bits than are on the 
display that you're numiiig on, you may want to create an offscreen buffer that's 
deeper than the screen and then take advantage of the dithering or halftoning 
mechanisms in QuickDraw GX to allow user manipulation. The code that cheeks 
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for changes in the screen view port’s halftone shntild give yon a good idea of how to 
do that. 


STEADY, NOW 

Now you umlerstand how to use double buffering to prevent fhdcer in your 
QuickDraw GX applicatinn. You may need to do sorne fine tuning of the screen 
buffering lihrar^^ to fit your purposes, Imt the result will he worth it. Users will 
appreciate the more professional look of your application and their eyes won\ drc 
as quickly as they peer at a flicker-free screen. 


RELATED READING 

• ''Getting Storted With QuickDraw GX" by Pete "Luke" Alexander, develop Issue 15. 

• Inside Macmtosh: QuickDraw GX Objects and Inside Macintosh: QuickDraw GX 
Graphics (Addison-Wesley, 1994). 


Thcmks to our technkoi reviewers Dove Btce, 
Brran Chrisman, Tom Dowdy, Davfd Hayward, 
and Ingrfd Kelly.* 




Add 3D to Your Applications 


Take Developer University’s 3-day Programming 
with QuickDraw 3D class and add a new dimension 
to your Macintosh applications. Learn how to 
use Apple’s exciting new QuickDraw 3D graphics 
library. This course teaches you the basics of 
creating, manipulating, and rendering three- 
dimensional objects in your applications. You’ll also 
learn about the new 3D human interface guidelines, 
and Apple’s new metafile formatter reading and 
writing 30 objects. 



Turn Your Applications Into 
Virtual Reality 

Take Developer University's 3-day Multimedia 
Development with QuickTime VR class and learn to 
create the next generation of multimedia 
applications using QuickTime VR, Apple’s new 
non-linear panoramic movie format. You'll learn and 
use the tools, techniques, and production processes 
involved in creating QuickTime VR scenes. As part 
ot a team, you’ll plan scenes, photograph 
panoramas, activate your scenes, and use the 
QuickTime VR tools to create a finished product. 


Dates Offered: 
May 20-22,1996 


DEVELOPER 


UNIVERSITY 


Dates Offered: 
April 16-18,1996 
May 21-23,1996 
June 17-21,1996 


Call to register now at (408)974-4897 or send e-mail to devuniv@applelink.apple.com. Courses are offered in Cupertino, 
Calitonia and Portsmouth, New Hampshire. Both courses are $900 each. Dates are subject to change. 
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The 
Manager 


MIKE MARINKOVICH 




A major change is taking place on the screen, which 
your application might not even know^ about! With the 
help of the Display Manager, the user can use the 
iMonitors control panel to rearrange displays, make 
resohition switches, add or remove a display, and move 
the menu bar frcuii one display to another — all 
without rebooting* However, the ease of changing a 
display for the user [loses new challenges for the 
developer if an applteation relies on a graphics device’s 
bounding rectangle to position, zoom, and grow' its 
windows* 

'!() meet this challenge, the Display Manager provides 
several new funetitins chat make it easier to gather 
information about the display environment and 
implement changes* f'll describe some of the more 
commonly used functions in this column* Til also 
discuss how to use a notification event to find out when 
a display has changed (an example is included on this 
issue’s Cd)), 

Two versions of the Display Manager are currently 
implemented in the system software* The information 
in this column applies to both versions* Display 
Manager version 1*0 is available on all PowerPC^"' 
pnicessor-based Macintosh computers and Color 
QuickDraw-capable Macintosh computers running 
System 7*5* Display Manager 2.0 is available on PCI- 
based computers running System 7.5*2* To determine 
whether the Display Manager is availalile, call Gestalt 
with the selector gestaltDisplayMgrAttr and check the 
gestaltDisplayMgrPresent bit of the response. To 
determine which version you have, call Gestalt with 
the selector gestaltDisplayMgrVers. 


MORE FUNCTIONS, LESS CODE 

The Display Manager includes several new functions 
that greatly simplify tasks that used to take a lot of 
code* For example, many applications need to query 
screen devices for bounding rectangles, pixel depths, 
and a variety of other things. Prior to the Display 
Manager, an application could use the GetDeviceUst 
function to retrieve the first graphics device record in 
the device list and call GetNextDevice for subsequent 
devices in the list* 'Fhe application would then need to 
use the Device Manager to determine whether the 
device was a screen device and whether it was active. 
With the Display Manager, you can do all this with 
tw^o functions: DMGetFirstScreen Device and 
DM GetNextScreen Device* 


GDHandle aDevlce^ 


aDevice = 

DMGetFirBtScreenDevice(dmOnlyActiveDisplays); 
while (aDevice 1= nil) { 

//Do something with the device* 


} 


// Get the next device in the list. 
aDevice ^ DMGetNextScreenDevice(aDevice, 

dmOnlyActiveDisplays)j 


'rhe Display Manager also introduces tw^o functions 
that make tt easier to retrieve information about the 
attached displays and to change their characteristics: 
I)MCheckl3isplayM(Hie and DMSetDisplayMode. 

DMC^heckDisplayMode determines whether a 
specific display motle and pixel depth are supported 
by the supplied graphics device* (A display mode is 
a combination of several interrelated display 
characteristics, such as resolution and scan timing*) 
'This function has two output parameters: modeOk 
and switchFiags. If the Boolean modeOk parameter is 
true, the screen device supports the requested display 
mode* The switchFiags parameter contains two flag 
luts that should be checked with the constants 
kNoSwitchConfirmBit and kDepthNotAvaikbleBit* 

• If kNoSwitchConfirmBit isn’t set, the requested 
mode is an optional mode and is only shown in the 
mode list of the Monitors control panel when the 
Option key is pressed (an optional mode requires 
confirmation from the user before it’s allowed)* 


MIKE MARINKOVICH [marink@apple.com] is □ member of fhe 
Printing, Imaging, and Grophics (PIGS) group in Developer 
Technical Support at Apple. He's been whiling av/oy his days (and 
many of his evenings) coming to grips with the Display Manager 
and other QuickDroW'reloted esoterica. When not indulging in his 


hobby, which obo happens to be playing around with the Toolbox 
and programming his Macintosh. Mike spends his time exploring 
the San Francisco Bay Area in his trusty Subaru. Mike's From 
Seattle and misses the rain/ 
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• kDepthNot/WailableBit indicates whether the 
requested pixel depth is available with the requested 
display mode* 

Once your application knows that the requested display 
mode and pixel depth are available, you can use the 
DMSetDisplayMode function to reconfigure the video 
display. If you pass 0 for the mode parameter, the 
Display Manager uses the device’s current display 
mode* 

If you like to change the display mode and pixel depth 
often, you can save the configuration and retrieve it at 
startup with the DMSaveScreenPrefs function. This 
function requires three parameters, which all take the 
value of NULL since they’re private to the Display 
Manager, (Go figure.) 

Identifying displays. Many of the Display Manager 
functions require a display ID (t\qie DisplayIDType) 
as a parameter, A display ID is a long integer diat 
uniquely identifies a screen display. Affiliating a display 
ID widi a graphics device can be usefid in cases where 
the graphics device might change or isn’t available* 

You can t)btain a display ID with the function 
DMGetDisplaylDByGDevice, which requires a 
graphics device as a parameter* Or you can retrieve the 
graphics device corresponding to a given display ID by 
calling DMGetCTDeviceByDisplaylD. Both fimcrions 
require the Boolean parameter failToMain* 

• If you set failToMain to true and the routine can’t 
find what it’s looking for (either the graphics device 
or the display ID), the routine returns information 
about the main graphics device rather than returning 
an error. 

• If you set fadToMain to false and the routine 
can’t find what it’s looking for, it will return 
kDMDisplayNotFoundErr. (For example, when a 
PowerBook goes to sleep, the display anight be 
removed.) 

KEEPING UP WITH THE CHANGES 

Now that the user is able to change a screen display 
without restarting, your application may want to 
reposition and resize its windows, update internal 
display-related data structures, or update nonstandard 
window definitions on the fly* 

If desired, the Display Manager c'an automatically 
adjust the positions of the windows that were onscreen 
before the change to keep them onscreen after the 
change, but it may not put them in the best possible 
positions. However, if you want to reposition and 
resize your window^s yourself, you need to set the 
isDisplayManagerAware flag in your application’s SIZE 


resource and install a callback procedure or an Apple 
event handler in your application so that you’ll know 
when a display has changed* 

Your application registers a callback procedure with the 
Display Manager ftmction DMRegisterNotifyProc. 
dlie display notification procedure takes a Display 
Notice Apple event parameter descnbing the changes 
that were made to the display* The notification callback 
is especially useful for control panels and other 
instances where high-level event handling in an event 
loop isn’t possible* Another benefit of the notification 
callback is that your application is informed on a more 
timely basts than through a high-level event, thus 
giving the appearance of seamless integration with the 
Display Manager. 

If you're using Display Monoger 1 you're not notified 
□bout depth chonges, and A5 isn't restored when you receive 
the notihcotion collbock.* 

You can also receive and process Display Notice events 
through an Apple event handler* Display Notice event 
handlers are installed like any other Apple event 
handlers, with the AEInstallEventHandler function: 

err = AEInstallEventHandler(kCoreEventClass, 
kAESystemConfigNotice, 

NewAE EventH andlerPr oc{DoAEDis p1ayC o n figC h an ge), 
0, false); 

To enable high-level events in your application, you 
need to set the isl lighLevelEventAware flag in the 
SIZE resource* (You’ll also need to support the 
required Apple events described in Inside Madntosh: 
lnte?7/pplkation C&nmmnication.) 

Wliether your application uses a notification callback 
or a high-level event handler, a Display Notice Apple 
event is passed to your routine* You can obtain a list of 
descriptor records (an AEDescList) from the Display 
Notice event witli the AECietParaniDesc function. 

Each descriptor record holds tw'o additional key'word- 
specific descriptor records: 

• keyDisplayOldConfig, which is a record of the 
display’s previous state 

• keyDisplayNewConfig, wliich is a record of the 
display’s current state 

You can obtain these records one at a time with the 
function AEGetNthDesc* 

To move and resize your application’s windows, you 
need to know which graphics device w'as affected, the 
old and new^ bounding rectangles of the device, and 
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Listing 1 . Handling the Display Notice event 


OSErr HandleNotification(AppleEvent Levant) 

{ 


OSErr 

GrafPtr 

AEDescList 

AERecord 

AEKeyword 

DisplaylDType 

unsigned long 

long 

Rect 


err; 

oldPort; 

displayList, aDiaplay; 

oldGonfig, newConfig; 

tempWord; 

displayID; 

returnType; 

count; 

oldRect, newRect; 


GetPort(&oldPort); 

// Get a list of the displays from the Display Notice Apple event. 

err = AEGetParainDesc(event, kAEDisplayNotice, typeWildCard, &DisplayList); 

// How many items in the list? 

err = AE Count11 ems(^ dis playLis t, & count); 

while (count > 0) { 

// Loop through the list. 

err = AEGetNthDesc(SdisplayList, count, typeWildCard, &tempWord, SaDisplay); 

// Get the old rect, 

err = AEGetNthDeBc(SaI>igplay, 1, typeWildCard, SftempWord, SoldConf ig); 

err “ AEGetKeyPtr(&oldConfig, keyDeviceRect, typeWildCard, SreturnType, &oldRect, 8, nil); 
// Get the display ID so that we can get the GDevice later, 

err = AEGetKeyPtr(&oldGonfig, keyDisplaylD, typeWildCard, sreturnType, &displayID, 8, nil); 
ii Get the new rect, 

err = AEGetNthDesc{&aDisplay, 2, typeWildCard, &tempWord, &newConfig); 

err = AEGetKeyPtr(&newConfig, keyDeviceRect, typeWildCard, ftreturnType, SnewRect, 8, nil); 

//If the new and old rects are not the same, we can assume that the GDevice has changed, 

// and the windows need to be rearranged, 

if (err — noErr && lEqualRect(anewRect, aoldRect)) 

HandleDeviceChange(displayID, anewRect); 

count—; 

err = AEDisposeDesc(&aDisplay); 
err = AEDisposeDesc(aoldConfig); 
err = AEDispoaeDesc(anewConfig); 


) 


err = AEDisposeDesc(&displayList); 
SetPort(oldPort); 


return err; 


} 
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possibly the pixel depth- All the information about the 
affected graphics device can be obtained from the 
descriptor list with keywt^rd-specific descriptor 
constants, which are defined in the Displays.h universal 
header file. You call xAEGetKcyPtr widi die various 
descriptor constants to extract the mfonnation you 
need. In particular, the constant keyDcviceRect extracts 
the bounding rectangle, and keyDisplaylD extracts the 
display ID- As previously inenrioned, you can convert 
a display ID to a graphics device with the function 
DMGetGDeviceByDisplayTD. 

Listing 1 shows an example of what to do after receiving 
3 Display Notice event from a notification callback or a 
high-level event handler. 

WHAT TO DO NOW 

The sample code on this issue's CD should provide a 
starting point for how to handle display notification 


events in your application. Additional documentation 
and sample code for the Display Manager are provided 
in the Display Manager Development Kit, which is also 
on the CD. 

The Mac OS Software Developer's Kit incudes the 
Disploy Manager Development Kit along with a lot of other 
development softwore. The Mac OS SDK is now port of the 
Developer CD Series (included in the Apple Developer Moiling, 
which is available through the Apple Developer Catolog).* 

T> iearn more about what the Display Manager can do 
for you, you should also take a look at the Displays.h 
universal header file. 

Now^ there's no excuse for your application to be in the 
dark about changes taking place on the screen. So why 
not keep your users happy and take advantage of the 
help that the Display Manager can give you? 


Thanks to Eric Anderson, David Hoyword, ond Ian Hendry For 
reviewing this column/ 


Mac OS SDK Edition 



edifion. 


The Developer CD Series now features a new 

Every quarter, along with the System Software edition and 
other vital information, the Apple Developer Mailing will 
include the Mac OS SDK, a collection of over 30 individual 
Software Developer Kits. Look to this CD for tools vital to 
writing software that takes advantage of Macintosh Toolbox 


services. 


Each Mac OS SDK CD contains: 

• system software extensions • programming interfaces 
and libraries • sample code • technical documentation 


In addition to the Developer CD Series, the Developer Mailing will bring you 
Apple Directions and other timely materials from Apple's developer support groups. 

For more information on the Developer Mailing or to subscribe, coll 
1-800-282-2732 in the U.S. 1-800-637-0029 in Canada [716)871-6555 elsewhere 
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NURB Curves: A Guide for the Uninitiated 


QuickDraw 3D mpports a fnathematical model for arbitrary curves 
and surfaces known as NURB {nonuniform rational B-splines). NURB 
curves are flexible and powetful, but using thefn effectively requires 
some understanding of the underlying ???atbematical theoty. This article 
presents an intuitive introduction to the mathematical concepts of the 
NURB model and how to use them, in your QuickDraw 3D programs. 



PHILIP J. SCHNEIDER 


One of the more powerful fennires of QuickDraw 3D is its ability to work with 
curves and surfaces of arbitrary shape. The mathematical model it uses to represent 
them is known as NURB, for nonunifonn rational B-splines. The NURB model is 
flexible and pt>w'erful, but for those unfamiliar with the mathematics, it can appear 
dauntingly complex. The existing books and articles on the subject tend to be 
rigorous, lengthy, and theoretical, and often seem to require that you already 
understand the subject in order tc) follow the explanations- 

'The mathematics really aren't au frightening, though, once you understand them, 
rhe aim of this article is to give vim an intuitive understanding of how NURB cun^es 
work- Later in the article, wedl look at some code to show you how’ you can start 
using NURB curves in your own programs — but you really do need to understand 
the theor)^ before you can start putting it to practical use. So please be patient while 
we slog tbrough the mathematical concepts: I promise well get around to some 
acuial programming before weVe through. Note also char this article is only about 
NURB cHf-oes; perhaps a fijture article will cover NURB .mfices and how to use 
curves and surfaces together 


Some writers olso use the s from “spline/ resulHng in the acronym NUffSS — but 
most avoid this usage because phrases like "a NURBS curve'" sound awkward, and "a 
NURBS surface" sounds perfectly hideous.® 


WHY NURB CURVES? 

Like any graphics package, QuickDraw 3D offers low-level geometric primitives for 
objects such as lines, points, and triangles. Because the representations of these 
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objects are mathematically exact — lines being defined by their two endpoints, 
triangles by their three vertices, and so forth — theyVe resolution independent and 
unaffected by changes in position, scale, or orientation. 

The low-level primitives can also be used to define arbitrarily shaped objects, such 
as a football or an automobile hood, but at the cost of these desirable mathematical 
properties; for example, a circle that’s approximated by a sequence of line segments 
will change its shape when rotated. One of the advantages of NURB curves is tliat 
tliey offer a way to represent arbitrary shapes while maintaining mathematical 
exactness and resolution independence. Among their useful properties are the 
following: 

• I'hey can represent virtually any desired shape, from points, straight lines, 
and polylines to conic sections (circles, ellipses, parabolas, and hyperbolas) to 
ffee-form curves with arbitrary shapes. 

• They give you great control over the shape of a curve. A set of vmitiiilpoints 
and knon\ which guide the curve’s shape, can be directly manipulated to 
control its smoothness and curvanire. 

• They can represent very complex shapes with remarkably little data. For 
instance, approximating a circle three feet across with a sequence of line 
segments would require tens of thousands of segments to make it look like 
a circle instead of a polygon. Defining the same circle with a NURB 
representation takes only seven control points! 

In addition to drawing NURB curves directly as graphical items, you can u.se them 
in various other ways that exploit their useful mathematical properties, such as for 
guiding animation paths or for interpolating or approximating data. You can also use 
them as a tool to design and control the shapes of three-dimensional surfaces, for 
purposes such as 

• surfiiccs of revolution (rotating a two-dimensional curve around an axis in 
three-dimensional space) 

• extruding (translating a curve along a curved path) 

• trimming (cutting away part of a NURB surface, using NURB curves to 
specify the cut) 

CURVES 101 

Before we go into the .specifics of NURB curves, let’s review some of the basic's of 
curve representation in general. 

Although QuickDraw 3D supports three-dimensional NURB curves, we’ll limit all of 
our examples and disaissions here to two dimensions. But everything we say about 
two-dimensional curves applies in three dimensions as well — the twf>-dimensional 
versions are just easier to visualize and easier to draw, 

A BIT OF HISTORY 

Back in the days before computers, architects, engineers, and artists would draw their 
designs for buildings, roads, machine parts, and the like by using pencil, paper, and 
various drafting tools. These tools included rulers and T-squares for drawing straight 
lines, compasses for drawing circles and circular arcs, and triangles and protractors 
for making precise angles. 

Of course, a lot of interesting-shaped objects couldn’t be drawn with just these simple 
tools, because they had curved parts that weren’t just circles or ellipses. Often, a curve 
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was needed that went smoothly through a number of predetennined points. This 
problem was particularly acute in shipbuilding: although a skilled artist or draftsman 
could reliably hand“draw such curves on a drafting table, shipbuilders often needed to 
make life-size (or nearly life-size) drawings, where the sheer size of the required 
curves made hand drawing impossible. Because of their great size, such drawings 
were often done in the loft area of a large building, by a specialist known as a 
loftsman. To aid in the task, the loftsman would employ long, thin, flexible strips of 
wood, plastic, or metal, called splines. The splines were held in place with lead 
weights, called dmks because of their resemblance to the feathered creature of the 
same name (see Figure 1), 



Figure 1. A draftsman's spline 


The resulting curves were smooth, and varied in curvature depending on the position 
of the ducks. As computers were introduced into the design process, the physical 
properties of such splines were investigated so that they could be modeled 
marhcmaticalJy on the comj^uter, 

DIRECT FUNCTIONS 

Our goal is to represent curves in a niaihematically precise fashion. One simple way is 
to think of the curve as the graph of a ftmetion: 


y =.flx} 


dlilce a simple one like the trigonometric sine ftincrion: 
y - sin X 

By pIfJtting the value of the function for various values of x and connecTing diem 
smoothly, we obtain the curv^e shown in Figure 2. 



Figure 2 * Plot of sine function values 
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In the case of curves drawn by the spline method, it turned out that with some 
reasonable simplilying assumptions, they could be mathematically represented by a 
series of cubic (third-degree) polynomials, each ha\^ng the fonti 

y = Ax^ + Bx^ + Cx + D 

At this point, the standard references typically go into a long, involved development 
of this idea into what are known as cnhk spline a/ZTet, eventually leading to the theory 
of NURB cui"ves. Such explanations are interesting, but not terribly intuitive. IF 
youVe interested in pursuing this subject further, you 11 find a good discussion in 
Miitheminkal Elernaits for Compnter Graphics. (Complete infonnation on this and 
other litentture references in this article can be found in the bibliography at the end*) 

PARAMETRIC FUNCTIONS 

Using direct fimetions to represent a curve fits our criterion of being mathematically 
exact, but it has one serious drawback: since we can have only one value ofy for each 
value of JIT, our curves can’t loop back on themselves. Thus, although we can make 
some nice smooth curves this way, there are a lot of interesting curves we mn^t make 
— not even something as simple as a circle* 

An alternative method, and the one well be using, is to define the curve with a 
parametricfiinction. In general, such fimetions have the form 

C?(r) = {mr(f)l 

where X{t) and }1(r) are functions of the parameter r (hence paramenic). Given a value 
of r, the function X(r) gives the corresponding \^alue of and F(0 the value of y One 
way to understand such fimetions is to imagine a particle traveling across a sheet of 
paper, tracing out a curve* If you think of die parameter t as representing time, the 
parametric function Q{t) gives the {x, y} coordinates of the particle at time t. For 
example, defining the functions X(f) and r(t) as 

X(f) = cos t 
Y{t) - sin t 

produces a circle, as you can verify by plugging in .some values of f between 0 and In 
and plotting the results* 

SMOOTHNESS 

One very importaut motivation for using NURB curves is the ability to control 
smoothness. The NURB model alkws you to define curves with no kinks or sudden 
changes of direction (such as an airplane-vring cross section) or with precise control 
over where kinks and bends occur (shaqi comers of machined objects, for instance), 

VVe all know (or think we do) what a nice, smooth curve looks like: it has no kinks or 
comers. If we were to sit on that moving particle as it traces out a parametric curve, 
we would experience a nice smooth ride with no stopping, restarting, or sudden 
changes in speed or direction: we %vouldn’t be heading nordi, say, and then turn 
completely east in an instant. This intuitive notion can be expressed in precise 
mathematical terms: Imagine an arrow that always points in the direction in which 
our hypothetical particle is traveling as it moves along the curve. Mathematically, the 
directi(^n arrow corresponds to the tangent of the curve, which can be computed as 
the derivative of the curve’s defining function with respect to the time parameter f: 

(3X0 
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In Figure 3, for example, the point on the curve corresponding to time is labeled as 
and the direction vector (tangent) at that point as QXt^). If the tangent doesn’t 
jump suddenly from one direction to another, the curve’s function is said to have 
first-derivative conthmity^ denoted by 0\ this corresponds to our intuitive notion of 
smoothness. 


Q(t^) 



Now look at the point marked C?{%)* where there’s a visible kink in the curve. The 
direction vector just a tiny bit to the left of that point, is wildly different 

from the one just a tiny bit to the right, Q\tg-\-a). In fact, the direction vector jumps 
instantaneousiy from one direction to another at point Mathematically, this is 
called a iUscontinuity. 

Many of you will recall from your college calculus that the derivative of a function is 
also a function, whose degree is one less than that of the origdnal function* For 
example, the derivative of a fourth-degree function is a third-degree function. The 
derivative of the derivative, called the second derivative, will then be of degree 2. 
This second derivative may or may not be continuous: if it is, we say that the original 
function \\ 2 .s secQfid-derhative amthuiityy or Cfi. As the first derivative describes the 
direction of the curve, the secemd derivative describes how fast that direction is 
changing. The second derivative thus characterizes the curve’s degi'ee of curvature, 
and so a -continuous curve is said to have curvatinr continuity. Wee’ll come back to 
these important concepts after weVe introduced NURB curves themselves, 

NURB CURVES 

Now that we know how parametric frinctions work, let’s see how we can use them to 
build up a definition for NURB curves* If we call our function Q, the leftside of our 
equation will look like this: 




where t is a parameter representing time. By evaluating this function at a number of 
values of r, we’ll get a series of {x, y] pairs that we can use to plot our curve, as shown 
in Figure 4* Now all we have to do is define the right-hand side. 

CONTROL POINTS 

One of the key characteristics of NURB curves is that their shape is determined by 
{among other things) tlie positions of a set of points called control points, like the ones 
labeled in Figure 5, As in the figure, the control points are often joined with 
connecting Hues to make them easier to see and to clarify their relationship to the 
curve. These connecting lines form what’s known as a control polygon. (It would 
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Figure 4, Plotting o paro metric function 

• ■ 




actually make more sense to call it a control polyline,'^ but the other is the 
conventional term*) 

The second curve in Figure 5 is the same curve, but with one of the control points 
(^ 7 ) moved a bit. Notice tliat the curve's shape isn't changed throughout its entire 
length, but only in a small neighborhood near the changed control point* This is a 
very desirable property, since it aUows us to make localized changes by moving 
individual control points, without affecting the overall shape of the curve* Each 
control point influences the part of the curve nearest to it but has little or no effect 
on parts of the curve that are farther away* 

One way to think about this is to consider how much influence each of the conti*ol 
points has over the path of our moving particle at each instant of time* At any time r, 
the particle's position will be a weighted average of all the control points, but w ith the 
points closer to tlie particle carrying more weight than those farther away. We can 
express this intuitive notion mathematically this way: 
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i = 0 


In other words, to find the position of the moving particle at a particular time, add 
up the positions of all the control points {B^ but vary the strength of each point's 
contribution over time We’ll explain the meaning of the subscript k shortly. 


The bounding volume returned by QuickDraw 3D for all oJher geometric 
primitives is o vofume tbot encloses the primitive itself. For NURB curves, however, the 
returned bounding volume encloses the curve's control points, rather than the curve itself. 

This is done For historical reasons, and is the normal practice in 3D graphics packages * 

BASIS FUNCTIONS 

The function which determines how strongly control point influences 

the curve at time f, is called the hashjimctim for that control point. In fact, the B in 
“B-spIines” stands for “basis.” The value of diis functinn is a real mimher such as 
0.5, vSo that a particular point Q{t) can be defined as, say, 25% of one control point’s 
position, plus 50% of another's, plus 25% of yet a third's. 'lo complete our NURB 
equation, we have to specify the basis function for each control point 

So how do we go about defining the basis functions? Remember that we want each 
region of the NURB curve to he a local average of some small number of control 
points close to that region, Wlien the moving particle is far away from a given 
control point, that conirol point has little influence on it; as the particle gets closer, 
the coniTol point affects it more and more. Then the effect dimini.shes again as the 
particle recedes past the control pf)int. 

Up to now, weVe been using the words “near” and “far” in a rather vague way, but 
the time has come to pin them down more rigorously. Because weVe defined our 
curve parametrically with respect to time, we can regard what weVe been calling a 
“part” or “region” of tbe curv e as a portion of the time interval the curve covers. For 
example, if our curve goes fi'om time t = 0.0 to t = 10.0, we can speci fy a particular 
region as extending from, say, / = 3.3 to t = 7.5. So we can say, bn- instance, that a 
control point is centered at time t = 5.0 and has an effect in the range from f = 3 J 
to r = 7.5. 

Figure 6 shows a typical example of what a basis function might look like: it has its 
maximum effect at some definite point in time and tapers off smoothly as it gets 
farther away from that point. If yon were awake during your college statistics course, 
you might recognize this as the familiar “bell curve” that we all learned to know and 
loathe. I'he cun^e in the figure shows that control point B^ has Its greatest 

effect (about 95%) at time / = 3.0 and tapers off to about 50% at r = 1,7 and / = 4.3. 

Since each control point has its own basis function, a NURB curve with, say, five 
control points will have five such functions, each covering some region of the curve 
(that is, some inretv^al of time). At time f = 2.3 in Figure 7, for example, control point 
^f} has a W'eight of ahoiit 0 2, /?| alxjut 0,7, and ff? about 0.05. As t goes from 0.0 to 
7.0, each control point's effect on the shape of the curve is initially 0, increases 
gradually to a Tnaxirnum, and then gradually tapers off again to 0 as we reach the end 
of its effective range. 

KNOTS 

Notice that all of the basis funcrions in Figure 7 have exactly the same shape and 
cover equal intervals of time. In general, we’d like to be able to vary the width of the 
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Time (t) 

Figure 6* Basis function for a control point 


N,^,(t) 



Figure 7. Uniform basis functions for a set of control points 

intervals (so that some control points affect a larger region of ilie curve and others a 
smaller region) and the maximum height of the curves (so that some control points 
affect the shape of the curve more strongly than others). That’s where the NU in 
NURB comes from: it stands for nonunifomi. 

Hie solution is to define a series of points that partition die time into intervals, which 
we can then use in the basis functions to achieve the desired effects. By varying the 
relative lengths of the intervals, we can vary the amount of time each control point 
affects the particle. The points demarcating the intervals are known as knots, and the 
ordered list of them is a knot i?ator (Figure 8). The knot vector for the basis functions 
showm in Figure 7 is (0.0, LO, 2d), 3,0, 4.0, 5.0, 6.0, 7.0}. This is an example of a 
imifor?n knot vector, which is why all the functions in the figure cover equal intervals of 
time. Figure 9 shows an example of a curve created vdth such a knot vector. 

Time (t) ii^i^i—'—*—‘—4—'—i^^ 

0 1 2 3 4 5 6 7 

Figure 8* A knot vector 
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Figure 9- NURB curve wifh uniform knoJ vector 

If we change the knot vector to {0,0, 1.0, 2*0, 3.75,4.0, 4.25, 6.0, 7.0}, we get a set of 
nonuniform basis functions like the ones shown in Figure 10, and a curve that looks 
like Figure 11 (using the same set of control points as in Figure 9). Notice diat the 
basis functions N 2 |(r) and associated with control points 82 and 8 ^^ respectively, 

arc taller and narrower than the others- If you compare Figures 9 and 11, yon1l see 
that the curve in Figure 11 is pulled more strongly toward control points 82 and 8 ^ 
than the one in Figure 9. 'riiis is because the basis functions for these control points 
have a greater maximum value. Also, the curve rapidly approaches these control 
y^oints and rapidly moves away: compare how tightly curved it is near these points, 
relative to the curve in Figure 9/1'his is a result of the narrower basis functions for 
these two control points: intuinvely, our moving particle has to traverse more space in 
relatively less time. Looking at die knot vector, you can see tiiat the knot intervals for 
these two control points are narrower than the others — {5,75, 4.0) and |4.0, 4.25) — 
meaning that dieir effects on the curve are concentrated in shorter time inter\'als. 


N^ Jt) N3 3(0 



Figure 10, Nonuniform basis Functions for a set of control points 


56 


develop 25 March 1996 








■ 



Figure 11. NURB curve with nonuniform knor vector 

DEFINING THE BASIS FUNCTIONS 

We’re now ready to complete our definition of a NUEB curve by giving an exact 
specification of the basis functions. In some respects, weYe free to use any sort of 
functions we’d like, but by choosing them careRilly, we ean get certain desirable 
effects. l"he definitions we’ll be using are as follows: 

N. {f) = P 

\o Otherwise 

where is the conventional notation for die /di knot in the knot vector 

This definition has a lot of stuff in it, and lots of subscripts — we’re getting into the 
real theoretical aspects of NURB curves here. Notice that the functions for higher 
values of the subscript k (called the order of the basis function) are built up recursively 
from those of lower orders. If k is the highest order of basis ftmction we define, the 
resulting NURB curve is said to he of order k or of degree ^-1. At the very bottom of 
the hierarchy, the functions of order 1 are simply 1 if ? is betw een the itli and {/+l)st 
knots, and 0 otherwise. 

The specifics of this particular set of basis functions, and how they came to be this 
way, are beyond the scope of this article; if you’re interested in learning more, you’ll 
find all the detail you could possibly want (and tlien some) in An Introduction to Splines 
for Use in CoTnputer Graphics and Geotnetric Modeling. However, we can at least mention 
a number of important characteristics tliat this choice of basis functions exliibits: 

• At any time r, the values of all the basis functions add up to exactly 1. 

• If all control points have positive weights, die curve is contained within a 
bounding region known as the convex hull. (See the book cited above for 
details.) 

• At any time t, no more than k basis functitins affect the curve, where k is the 
order of the curve. 

• A curve of order k is defined only where k of the basis functions are nonzero. 
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This last characteristic is of more than theoretical interest: a cubic (degree-3 or 
order-4) NURB curve with a knot vector of, say, |0.0, LO, 2,0, 3,0, 4,0, 5,0, 6,0, 7.0} 
only goes from f = 3.0 to f ^ 4.01 The rule is that die curve begins at the ^ch knot 
from the beginning of the knot vector and ends at the i*th knot from the end. 

KNOTS AND KINKS 

I should point out here that nonuniform knot vectors aren’t really very useful for 
controlling the shape of a curve. (In fact, moving control points around direcdy isn’t 
that useful, either — but well get to that later.) Instead, nonuniforoi knot vectors 
have wo important uses: 

• You’ve probably noticed that all of our NURB curves so far have had their 
endpoints just “floating in space”; that is, the curve’s endpoints don’t coincide 
with any control point. In reaJ life, though, we generally want to be able to 
conm>l the exact placement of the endpoints, and most often we want them 
to coincide exactly with the first and last control points. 

• You may also have noticed that the curves displayed so far are quite smooth, 
WTiile this is usually a good thing, we sometunes need to create a curve with 
a lank or corner. 

We can accomplish both of these goals by using a rather extreme case of nonunifonnity: 
giving several consecutive knots the same value of f! For example, a knot vector like 
{ 0 . 0 , 0.0, 0,0, 3,0, 4.0, 5,0, 6.0, 7,0} produces a set of basis functions like those in 
Figure 12 and a curve (using the same control points as before) tiiat looks Like Figure 
13. Looking at Figure 12 , you can see that at t = 0 , the basis functions associated witit 
all hut the first control point have a f) value — so basis function A/q (the one for 
control point has total omcrol over the curve. Thus the curve ar f = 0 coincides 
with the first control point. 

If wc hunch up some knots in the middle of the knot vector (0,0, LO, 2,0, 3,0, 3.0, 5,0, 
6 . 0 , 7 . 0 }, we get the basis ftinctions shown in Figure 14 and the curv'e in Figure 15, At 
f = 3.0, all the basis ftinctions except N 2 3 (f) have a 0 value — so control point Bj is the 
only one to affect the curve at that instant, and thus the curve coincides with that 
conmjl point. 



Figure 12. Basis functions for a curve with multiple identical knots at the beginning 
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Figure 13. NURB curve with multiple identical knots at the beginning 


In matliematical termSj continuity (smoothness) is an issue only at the joints defined 
by the curvets knots, where two segments of the curve meet; between the joints, the 
curve is perfectly smooth and continutms. A typical curve, in which each j<]int 
corresponds to a single knot, has continuity where fi is the degree of the curve. 
So a cubic (degree-3 or order-4) curve has second-derivative continuity (C^) at each 
joint if all the knots are distinct. If two knots coincide, the continuity at that joint 
goes down by one degree; if three coincide, the continuity goes down another degree; 
and so on. 

This means you can put a kink in the curve at a particular point by adding knots to 
the knot vector at that point. Later, well look at some code that shows how to do 
this. We*l] also see how you can use tliis same technique of knot insertion to convert a 
curve from NURB to Bezier representation. 



Figure 14. Basis functions for a curve with multiple identical knots in the middle 
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Figure 15. NURB curve with muiMple identrcal knots in the middle 

RATIONAL CURVES 

Now that weVe learned all about control points and knots md basis functions, 
we understand NUB (oonuniform B-spline) curves. But what about the rest of 
die acr<myTn? WeVe still missing the R in NURB, It’s time to talk about rational 
curves. 

If yoiiVe sneaked a peek at QuickDraw 3D’s NURB definitions, you may have 
wondered wdiy it uses a hiur-dimensional representation For three-dimensional 
c()ntrol points: [x,y^ z, 2 i’} instead of just s}. The reason for the extra coordinate 
is that it aUows us to exactly represent conic curves (circles, ellipses, parabolas, and 
hyi^crholas), as w-ell as giving us more control over the shape of other curves. The 
fourth coordinate, is customarily referred to as the weight of the conm)l point. 
Orilinarily, each control point carries a w^eight of LO, meaning that they all have 
equal influence on the shape of the curve. Increasing the w'cight of an individual 
control point gives it more influence and has the effect of “pulling” the curve toward 
that point (see Figure 16). 


B 


3 



Figure 16, Increasing the weight of a control point 
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Curves that are defined in this way, with a weight w for each control point, are called 
rational airves. MathematioiUy, such curves are defined in four-dimensional space 
(since the control points have four components) and are projected down into three- 
dimensional space, Visnalizing objects in four dimensions is a hit difficult (let alone 
drawing them in a diagram), but we can understand the basic idea by considering 
rational fa^o-dimensional curves: that is, curves defined in three-dimensional space 
and projected onto a plane, as shown in Figure 17* 


Projection line 


Projection line 


Projection line 


I /axis 



Figure 17. Projecting a three-dimensional curve into two dimensions 


This is essentially the same process as projecting a tliree'dimensionai model onto a 
two-dimensional screen with a perspective camera. The basic method for such 
perspective projection is to divide by the homogeneous component of die vemex (that 
is, w); we use an analogous approach to project our four-dimensional rational curve 
into three-dimensional space. Mathematically, then, we must incorporate this division 
into our earlier definition for a B-spline curve: 


n-\ 

- 

i - 0 

The are die projecdons of the four-dimensional control points and the are their 
weights. 

There are two different conventions for representing the control points in terms of 
their four-dimensional coordinates {a:, y, 

♦ Hoinogeneom, in w^hich the coordinates represent the paint’s position in four- 
dimensional space. To project it into three dimensions, the components must 
all he divided through by w. Thus the pointis three-dimensional position is 
actually {x/Wjy/w^ z/w}. (Note tiiat^u/Ti^ is alwa}^ L) 
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• Weighted Emiidean, in which the coordinates are already considered to have 
been di\ided through. Thus the first three components {x^ y, z} direcdy 
represent the point’s position in three-dimensional space and the fourth (w) 
represents its weighL 

QuickDraw 3D uses homogeneous representation, as do most technical papers and 
other graphics libraries. 


CONIC SECTIONS 

I said earlier that we could use the rational aspect of NURB curves to create conic 
sections (such as circles and ellipses). Conic sections are so called because they’re the 
curves we get by intersecting a cone with a plane; the angle at whicli the plane 
intersects the cone detennines whetlier tlie resulting curve is a circle, an ellipse, a 
parabola, or a hyperbola. Strictly speaking, hyperbolas and parabolas are of infinite 
extent — bur infinite curves are generally not useful in graphics applications {besitles 
being very hard to compute a bounding box for). So we"11 restrict our discussion to 
conic arcs. 

Since conic curves are quadratic, we can represent them by quadratic (degree-2 or 
order-3) NURB curves. The practical question, of course, is which NURB curve. 
Although the proof is beyond the scope of this article, the following method 
(illustrated in Figure 18) can l.>e used to generate conic arcs: 

• The curve is defined by three control points. The first and last are the 
endpoints of die conic arc, while the placement of the inner control point 
helps detemiine the sliape of the curve. 

• ' ITe weights of the first and last control points are 1.0. 

• A weight less than 1.0 for the inner control point generates an ellipse; a 
w'cight equal to 1.0 generates a parabola; a weight greater than 1.0 generates 
a hyperbola. 

• riie knot vector is {0.0, 0.0, 0.0, l.O, LO, I.O}. 


IV - 0.25 


w = 1.0 


TiJ = 3.0 



Elliptical ore 



Figure 18. Constructing conic arcs 



Probably the most common form of conic arc, parrioilarly in modeling and design 
applications, is a circular arc. Since a circle is simply a special case of an ellipse, the 
method lor constructing a circular arc is a special case of the general method for 
elliptical arcs: 

• The legs of the control polygon are of equal length (tliat is, the control 
triangle is isosceles). 
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• The chord connecting the first iind last control points meets each leg at an 
angie 0 equal to half die angular extent of the desired arc (for instance, 50° 
for a 60° arc). 

• 'rhe weight of die inner control point is equal to the cosine of 6. 

• The knot vector is {0.0, 0.0, 0.0, 1.0, Id), 1.0), just as before. 

Figure 19 illustrates this construction. (In this case, the control triangle is equilateral, 
so die angle 0 is 60° and the resuldng arc is 120°, or one-third of a circle.) 


w = cos 0 



Figure 19. Constructing a circular arc 

Note that the foregoing method can only produce circular arcs less than 180°; for 
larger arcs, we have to piece together several NLIRB curves. So to draw a complete 
circle w'e could combine three 120° arcs, or four 90° arcs. However, it’s possible to 
represent these three or four separate arcs as a single curve and to make a circle with 
only one NURB curve. Figures 20 and 21 show^ how^ to do it with three and four arcs, 
respecdvely. 


^5 = (I, 1.732,0.5} 


= {1, 1.732,1} 



R^ = {3, 1.732, 1] 


= (0, 0, 0.5} = {2, 0, 0} B^ = {2, 0, 0.5} 



Figure 20. Constructing a circle with three ores 
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Figure 21, Constructing a circle with four arcs 


NURB CURVES IN QUICKDRAW 3D 

By now you’re probably saying, “Enough theory already —- how does all this relate to 
Macintosh programming?” So let's finally look at QuickDraw 3D's data stmcmres 
and routines for working with NURB curves. 

DATA STRUCTURES 

If you’ve been following tlie discussion so far, you can probably guess the contents of 
the data structure representing a NURB curve; the order of the curve, its control 
points, and its knots. There’s also the usual QuickDraw' 31) attribute set, so you can 
draw' your curves in, say, fuchsia or vennilion. Here are the definittonsr 

typedef struct TQ3RationalPoiiit4D { 
float x; 
float y; 
float z; 

float w; 

} TQ3RationalPoint4D; 

typedef struct TQ3NURBCurveData { 


unsigned long 

order; 

// 

Order of the curve 

unsigned long 

numPoints; 

// 

Number of control points 

TQ 3H:at ion a 1 Po int 4 D 

^controlPoints; 

// 

Array of control points 

float 

*knots 1 

// 

Array of knots 

TQ 3 At tributeS et 

cnrveAttributeSet; 

// 

QuickDraw 3D attributes 


} T03KURBCurveData? 

Alost of this is pretty straightforw'ard, bur here are a few' things to keep in mind: 

• The order of the curve must be betw^een 2 and 16, inclusive. Order 2 gives 
you a polyline effect; the most common orders are 3 (quadratic) and 4 (cubic). 

• The control points are represented in homogeneous form, meaning that you 
have to divide the ar, y, and z components by the w component to find the 
point’s actual position in three-dimensional space. 

• The w component of each control point must be positive. 
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• I'he number of control points must be equal to or greater than the orden 

• The number of knots must be equal to the number of control points plus the 
order of the curve. 

• 'rhe knots must be specified in nondecreasing order. 

• If ^ is die order of the curve, there can't be more than knots with the 
same value (except at the beginning or end of the sequence, where k 
consecutive equal knots are allowed)* 

• The attribute set should contain only attributes that make sense for a curve. 
Most often, the attribute set will either be NULL or simply contain a color. 

RENDERING A NURB CURVE 

If youVc familiar with QuickDraw 3D, you know that there are two ways to render a 
graphical enti ty (called a geometry in QuickDraw 3 D terminology): retained mode and 
immediate mode. In retained mode, you first create an object representing the figure 
you want to draw, then use this ntained object to do your drawing. (See the article '^The 
Basics of QuickDraw 3D Geometries" in develop Issue 23 fur more on this*) Listing 1 
shows how this works for a NURB curve. First we initialize a TQ 3 NURB Curve Data 
structure describing the curve to be drawn; we use this structure to create a retained 


Listing 1. Rendering a NURB curve in retained mode 

TQ3 Geome t r y Ob j ec t c u rveOb j e c t; 

TQ 3 NURBC urveDat a c urveD at a \ 

static TQ3RationalPoint4D 

controlPoints[ 4 ] = { 


{ 0, 0, 0, 1 }. 

{ 1, 1, Or 1 }r 

{ 2, 0, 0, 1 }, 

{ 3, 1, 0, 1 } 


} r 

static float 

knots[ 8] = { 


0, 0, 0, 0, 1, 1, 1, 1 

}; 

// Initialize the data structure* 

curveData * order 

= 4? 

curveData* numPoints 

= 4j 

curveData,controlPoints 

= controlPoints? 

curve D ata * k no t s 

“ knots? 

curveData *curveAttributeSet 

NULL? 

// Make a retained object* 


curveObject = QSMIRBCurve New(&curveData) ? 

// Use the retained object to 
Q3View StartRendering(view) ? 
do { 

render the curve. 

QSGeometry Submit{cuirveObject, view); 

} while (Q3View EndRendering(view) == kQ3ViewStatusHetraverse )? 

// Dispose of the curve object. 

QSObject Dispose(curveObject) 

/ 
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object with the QuickDraw 3D hmction Q3NURBCurve_New, and then we pass the 
resulting object to Q3Geoinetry_Submit to render the cm’\^e. Finally^ we dispose of 
the retained object we created* 

The equivalent drawing operation in immediate mode uses exactly die same code up 
to the point where the object is created. Instead of creating the retained objectj we 
simply pass the TQ3NURBCur\"eData structure directly to the QuickDraw 3D 
function Q3Nl-IRBCurve_Submit to be rendered immediately: 

// Render the curve directly. 

Q3View_StartRendering(view); 
do { 

Q3HURBCurve_Submit(ficurveData, view); 

} while (Q3View_EndRendering[view) — kQ3ViewStatusRetraverse)? 

CONTROLLING SUBDIVISION 

QuickDraw 3D doesn’t render NURE curves directly — as it docs, say, lines or 
triangles* To draw a NURB curve, the tenderer has to break it up into a sequence of 
lines or polylines* The more lines it’s broken up into, the smoother it looks, but of 
course the longer it takes to render. Before rendering a curve, you have to tell the 
renderer how finely you want it subdivided* 

'riiere are three ways of doing diis, denoted by the values of an enumerated data type: 

typedef enuM TQ3SubdivisionMethod { 
kQ3SubdivxsionHethedConstant, 
kQ3SubdivisionMethodWorIdSpace, 
kQ3 SubdivisionMethodScreenSpace 
} TQSSubdivisionHethod; 

• The first method, kQ3SubdivisionMethodf kaistant, says to subdivide die 
cuiwe into a polyline witli a specified number of segments bctV'cen each pair 
of joints. 

• The second metiiod, kQ3SubdivisionMcthodVVorklS[)iice, says to subdivide 
the curve so that the length of each line segment is no longer than a specified 
value, measured in world space. 

• The third metiiod, kQ3SybdivisionMethodScreenSpace, is similar to the 
second, hut the measurement is done in screen space. 

d'he following data structure specifies the subdivision method to use and the relevant 
parameter values: 

typedef struct TQ3SubdivisionStyleData { 

TQ3SubdivisionMethod method; 
float cl? 

float c2? 

} TQ3SubdivisionStYleData; 

NURB curves use only the cl component; the other is for NURB surtaces* A couple 
of things to note: 

• You should set both cl and c2 to legitimate values* QuickDraw 3D doesn’t 
know whether a curve or a surface is coming up, so it always checks both 
parameters for validity* If you’re only drawing a curve, you may as well set c2 
to the same value as cl * 
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• If you specify an unreasonable value for either parameter, QuicIcDraw 3D 
will substitute a more reasonable one and issue a warning. It won't let you 
subdivide a curve at a million positions! 

• For method kQBSubdivisionMethodConstant, cl should be a whole number 
greater tlian 0; fractional values will be Quncated. 

• If you don't specify a subdivision style, the default value will be used. 

Expanding on our example of immediate mode rendering, the following code 
will render our NURB curve with a five-segment polyline between each pair of 
knots: 


TQlSubdivisionStyleData 


subdivData? 


subdivData.method = kQ3SubdivisionMethodConstant? 
subdlvData.cl ^ subdivData<c2 ~ 5; 

Q3View_StartRendering(view); 
do { 

Q3 SubdivisionStyle_Submit(S subdivData, view); 

Q3NURBCurve_Submit(&carveData, view); 

} while (Q3View_EndRendering(view) == kQSViewStatusHetraverse)j 

EDITING NURB CURVES 

If you're rendering your curve in immediate mode, you can edit the curve by 
simply modifying its control points, weights, and knot vectors directly in the 
TQ3NURBClurveData structure. If you’re using retained mode, QuickDraw 3D 
provides calls to retrieve and set individual control points and knots: 

TQ 3 Status 03 KURBC u rve_GetCo nt roIPoiat(TQ3 Ge ometryOb j ec t c u rve, 

unsigned long pointindex, TQ3RationalPoint4D *point4D); 

TQSStatus Q3NURBCurve_SetControlPoint{TQ3G6ometry0bject curve, 

unsigned long pointIndex, const TQ3RationalPoint4D *point4D); 

T03 Status Q3NURBCurve_GetKnot{TQSGeometryObject curve, 
unsigned long knotIndex, float ^knotValue); 

TQ3 Status Q3l!aiJRBCurve_SetKnot (TQSGeometryObj ect curve, 
unsigned long knotindex, float knotValue); 

Because weVe not interacting with items that are objects themselves, there are no 
reference counts involved and no need to dispose of any data structures. Note, 
however, that if you edit a knot, the resulting knot vector must remain nondecreasing 
and follow the limitatioes described earlier for multiple knots. 

You may have noticed that there are no calls to add, delete, or reorder control points 
or knots. Instead, QuickDraw 3D provides calls for retrieving and replacing the 
entire TQ3NURBCurveData structure from the retained object: 

TQ 3 S t atu s Q 3 NURB Cu rve_Ge t Dat a(TQ 3 Geomet ryOb j ec t c u rve, 

TQ3NURBCurveData *nurbCurveData ); 


TQ3 Status Q3NURBCurve_SetData(TQBGeometryObj ect curve, 

const TQ3NURBCurveData *nurbCurveData); 
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If you want to change the number of control points and knots in a curve, you have to 
make a local copy of the data structure you obtain (rom Q3NURBCurve_GetData 
(making sure to allocate extra space for the new knots and control points), modify the 
arrays in the local copy, and store it back into the object with Q3NURBCurve_SetData. 
You must then call the following routine to dispose of the data you received from 
Q3NURBCurve_GetData: 

TQ3 Status Q3NURBCurve_EmptyData(TQ3l!JURBCurveData *nurbCurveData) ; 

However, if youfre going to be modifying the NURB curve frequently, you should 
probably be working in immediate mode and not using a retained object at all. 

KNOT INSERTION 

In general, the more control points we define for a NURB curve, the more control 
we have over its shape. It would seem reasonable that we could add more control 
points without changing the shape of the curve, and in fact diis turns out to be true. 
Remember, diough, that there’s a fundamental relationship among the knots, the 
control points, and the order of the curves the number of knots is equal to the 
number of control points plus tiie order. For example, a cubic curve (order 4) with 9 
control points will require 13 knots. So every time we adtl a control point, we also 
have to add an extra knot — and make sure all die control points are in the correct 
locations to keep die curve’s shape the same as before. 

In practice, we actually take the reverse approach: we decide where to adtl a new 
knot, then compute die location of the ctuTcsponding new control point (as well as 
the new locations of some of the existing ones). For example, if we take the curve 
depicted earlier in Figure 9 and insert a new knot at i = 3.6, we get a new curve with 
exactly the same shape but with a new set of control points (Figure 22). 









h 


Figure 22. Inserting a knot 


This operation of knot imenmi is a fundamental one in working with NURB curves. 
It’s direedy useful in both modifying (editing) and rendering cur\^es, and can also be 
used to convert a NURB curve to Bezier representation. After a brief discussion of 
the mathematical algorithm for inserting a knot, we’ll look at some example C code 
for implementing it. 
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THE ALGORITHM 

We Stan with a NURB curve represented by 


/-o 

with a knot vector Xy, Suppose we want to vidtl a new knot where 

^ ^ riew knot vectori is simply the old knot vector with inserted 

between Xf and The new curve will he defined by 


n -1 
i = U 

with knot vectors 

Now we have to figure out not only where the new control point is located and where 
it goes in the ordered vector of control points, but also how to adjust some of the 
existing control points to keep the shape of the curve unchanged; this process yields 
the new control point vector, B. ft turns out that the relationship between the old and 
new control points is 

Bj = 0- ^pBj_i + ajBj 


where a is defined by 


aj = i 


^new 




j < i-k+i 
i-k+2 <j < i 
j > i+1 


ITe proof of this is relatively simple, but w^e don\ have the time or space to go into it 
here, for a hill discitssion, see Curves and Surfaces in Computer Aided Gemretrk De.dgn. 

THE IMPLEMENTATION 

Listing 2 shows a function to implement this basic algorithm. The fiinctifin, which is 
included on this issuers CD, accepts a QuickDraw 3D NLTRB-curv^e data structure as 
an argument, along with the value of the new knot to insert, and returns a new data 
structure representing the same cun^e with the new knot inserted. For brevity, the 
function performs no range checking on die inserted knot, hut simply assumes that 
it falls within the legal range and that the resulting knot vector obeys the usual 
limitations on multiple knots. Note also that the code shown here does no checking 
on die results of memory allocation requests, though of cc)urse you should always 
perform such checks in real life. 

EVALUATING NURB CURVES 

Recall from our earlier discussion that if we have two knots at the same location, we 
lose one degree of continuity; with three identical knots, we lose two degrees of 
continuity; and so on. This process can be repeated until, when we reach k—l 
identical knots (where k is the order of the curve), we have no continuity at all at the 
given point. In this case, the curve at that point coincides directly with a control 
point, as we saw in Figure 15. 


NURB CURVES; A GUIDE FOR THE UNINITIATED 


69 






Listing 2. Inserting □ knot 

static TQlKURBCiirveData *InsertKnot 


(TQ3MIRBCurveData 

*oldCurveData, 

// Old curve 

float 

tNew) 

// Knot to insert 


TQ 3NDRBCurveData 

*newCurveData; 

// 

New curve after adding knot 

unsigned long 

k; 

// 

Order of curve 

unsigned long 

n; 

// 

Nmnber of control points 

TQ3RationalPoint4D 

*b; 

1/ 

Old control point vector 

TQ 3 RationalPoint4 D 

*bHat; 

n 

New control point vector 

float 

*x; 

// 

Old knot vector 

float 

*xHat; 

// 

New knot vector 

float 

alpha; 

n 

Interpolation ratio 

unsigned long 

i; 

n 

Knot to insert after 

unsigned long 

j; 

n 

Knot index for search 

TQ3Boolean 

foundindex; 

// 

Insertion index found? 


// Set tip local variables for readability < 
k = oldCurveData->order; 
n = oldCurveData->ntmLPoints; 

X = oldCurveData->knot9; 
b = oldCurveData->controlPoiiits; 

II Allocate space for new control points and knot vector. 
bHat ^ malloc((n + 1) * sizeof(TQ3RationalPoint4D))? 
xHat = malloc({n + k + 1) * sizeof(floatJ); 

// Allocate data structure for new curve. 
newCurveData iiialloc(sizeof (TQ3UURBCurveData)); 
newCurveData->order = k; 
newCiirveData->numPoints = n + 1; 
newCurveData->controlPoints ^ bHat; 
newCurvaData->knots = xHat; 
newCurveD a t a->curveAt t ribute Set = 

(oldCurveData->curveAttributeSet — NULL) 

? NULL 

: Q30b 3 ect_Duplicate(oldCurveData“>curveAttributeSet); 

// Find where to insert the new knot, 
for (j = 0, foundindex = kQ3False; j<ntk;j++) { 
if (tNew > x[j] ts tNew <= x[j + 1]} { 

i = 

foundindex = kQ3True; 
break; 

// Return if not found, 
if {ifoundindex) { 
return (NULL); 

} 

(continued on next page} 
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Listing 2. Inserting a knot (continued) 

if Copy knots to new vector* 
for (j=0; j<n+k+l? j++) { 
if (j <= i) { 
xHat[jJ = xtj]; 

} else if {j = i + 1) { 
xHat[j] = tKew? 

} else { 

xHat[j] = x[j - 1]; 

} 


// Compute position of new control point and new positions of 
// existing ones, 
for (j - 0; j < n + 1; jt+) { 
if {j <=^ i - + 1) i 

alpha - 1; 

} else if {i - k + 2 <= j && j <= i) { 
if {x[j + k - 1] - x[jl = 0) { 
alpha = Q; 

} else { 

alpha = (tNew - x(j]) / (x(j + k - 1] - x[jj); 

> 

} else { 

alpha = 0; 


if (alpha == 0) { 

bHat[j] = b[j - IJi 
} else if (alpha ==1) { 

bHat[j] = b[j]; 

} else { 

bHat[j].x = (1 - alpha) * b[j 

bRat[j]*y = (1 * alpha) * b[j 

bHat[j],z = {1 - alpha) * b[j 

bHat[j]*w - (1 - alpha) * b[j 

} 

> 


1].X + alpha * b[j].x; 
l].y + alpha * b[j].y; 
1].z + alpha * b[j].z; 
l]*w + alpha * b[j].w; 


return (newCurveData); 


We Ve just seen that we can add a knot and calculate the new control points. If 
we take this “new” curve (really just tlie old one with more knots) and add in that 
same knot again and again, until we have knots in the same place, we’ll end up 

with a control point that lies exactly at We can use this technique to calculate 

the location of a particular point on the NURE curve: simply keep inserting knots at 
the point of interest until there are ^-1 of them, at which time the newest control 
point created will lie at the desired point on the curve. 


We ean also use this approach to render a curve: by adding emmgh knots at some 
number of successive points in rime t, we’ll end up with a list of evaluated points on 
die curve, which we can then render as a polyline. The greater the number of 
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evaluation points^ the more segments the poly line will have, and the more closely the 
resulting image will approximate the curve. 

This isn't the most efficient algorithm; a number of better alternatives ore 
avatlable. For example, see Ao iniroducHon to Splmes #br m Computer Graphics 
and Geome/r/c tAodel'mg for a description of the Oslo algorithm, which is significantly 
more efficient if you're adding more than o few knots.* 


NURB CURVES AND BEZIER CURVES 

If you Ve familiar with Bezier curveSt you may be wondering how they relate to NURB 
curves. In particular, if your application currently uses Bezier curves, how can you 
draw' them w'hen QuickDraw 3D currently only supports NURB curves? Although a 
thorough treatment of the subject is beyond the scope of this article, you*lI he happy 
to learn that Bezier curves can actually he viewed as a subset of NURB curves. As a 
result, converting from Bezier Co NURB representation turns out to be trivial, 

CONVERTING BEZIER TO NURB CURVES 

Kerens all it takes to convert a Bezier curve to NURB format: 

1. Use the Bezier control piunts as the NURB control points. If the Bezier 
control points are rational (that is, if they have four components {jt, y, wW 
make sure theyVe in homogeneous rather than weighted Euclidean form. If 
they’re noiirational (have no w component), simply set w - 1.0 for each 
NURB control point. 

2. Set the order of the NURB curve to the number of control points. Bezier 
curves typically have three or four control points, corresponding to quadratic 
(order-3) or cubic (order-4) NURB curves, respectively. 

3. Oeate a knot vector with 2k elements, where k is the order of the curve. Set 
the first k knots to 0.0 and the last k ro 1.0. 

Listing 3 shows a lunction to perform the conversion (it’s included on this issue’s 
CD). The Bezier cun^e is assumed to be represenretl by a data structure of the form 

typedef struct BezierCurve { 
unsigned int order; 

PointiD *controlPoints; 

} BezierCurve; 

where the numberof control points is equal to the order of the curve. The function 
returns a TQ 3 NURB Curve Data structure representing the equivalent NURB curve. 
Once again, weVe saved code space by leaving out the necessary checks on the results 
of memory allocation requests. 

CONVERTING NURB TO BEZIER CURVES 

Converting a NURB curve to Bezier format is more complicated than the other way 
around. As we’ve just seen, any Bezier curv^e can be represented by a particular type of 
NURB curve, having half its knots at one end and half ai the other. The converse, 
however, isn’t true: an arbitrary NURB curve can’t, in general, be represented by a 
single Bezier curve. In fact, it generally requires several Beziers to represent a single 
NURB curve: one for each distinct segment of the curve, as defined by its knot vector. 

Recall that each segment of a NURB curve is affected by some subset of the control 
points. If we take each segment and add knots to both ends, generating a new^ set of 
control points each time, until each end has a number of knots equal to the order of 
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Listing 3. Converting a Bezier curve to NURB format 

TQ3NUSBCurveData *Be 2 ierToNURBCurve(BezierCurve *be2Cuirve) 

TQ3NURBCurveData *nurbCurveData; // NURB curve data structure 

unsigned long k? // Order of curve 

Point3D *b; // Bezier control point vector 

unsigned long i; // Control point or knot index 

// Set up local variables for readability, 
k = bezCurve->order; 
b = bezCurve->controlPoints; 


if Allocate data structure for new curve, 
nurbCurveData = niaIloc(sizeof {TQ3NURBCurveData)) ? 
nurbCurveData->order = kj 
nurbCurveData->numPoints = k; 

nurbCurveData->controlPoints - malloc{k*sizeof{TQ3RationalPoint4D)); 
nurbCurveData->knotB = malloc(2*k*sizeof{float); 


// Create the control points, 
for {i = 0; i < k; i++) { 

TQ3RationalPoint4D_Set(&nurbCurveData->GontrolPoints[i], 

b|i].x, b[i].y, b[i].z, 1.0); 


} 


// Create the knots, 
for (i = 0; i < k; i++J { 

nurbCurveData->knots[il ^ 0.0? 
nurbCLirveData->kiiots [ 1 + k] = 1.0; 

// Set attributes here, if desired, 
nurbCurveData->nurbCurveAttributes = NULL; 


return (nurbCurveData); 

} 


the curve, the result will be a Bezier representation of that particular segment. Do 
this for each segment, and we’ll end up with a series of Bezier curves that, taken 
together, l(K)k exactly Like the original NURB curve. 

DESIGNING WITH NURB CURVES 

The topic of how to use NURE curves in design could easily fill a book; we’ll have to 
be content with just a brief discussion, along with some pointers for further reading. 

The most olmous capabdities an application program can offer for creating and 
modifying NURB curves are 

• interactive placement and movement of control points 

• interactive placement and movement of knots 

• interactive setting and modification of control-point weights 
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These capabilities can be moderately effective, but actually using them to model a 
desired shape turns out to be difficult and awWard. In addition, modifying a control 
point, knot, or weight will generally affect parts of the curve that the user wants to 
remain unchanged. 

One problem that has been explored extensively is that of automatically creating a 
curve that goes through (interpolates) a given set of points, which may have been 
interactively placed by the user or perhaps obtained by some sort of data sampling. 
Indeed, it might be said that this w^as one of the original motivations for the 
mathematical development of spline curves. The first straightforw^ard attempts 
yielded less than satisfactory results, but later efforts w^eren^t too bad and may be 
usefiiJ if the curve must pass exacdy through the given points. Often, however, we 
only need to approxiimte the given set of points with a spline curve. The points may 
have been obtained by sampling the user’s freehand drawing with a mouse or tablet, 
or perhaps by measuring a physical object or extracting edge information from a 
glyph in a Ijitmapped font. In diese cases, we probably want to preserve features such 
as endpoints and corners, hut the remaining data samples may be noisy or nonsmoodi 
and need not be fitted exactly. Techniques for both exact and approximate fitting can 
be found in Pbomix: An Interactive Cm-ue Design Systmi Based m theAutmmtk Fitting 
of Hand-Sketched Cm-ves and A User Interface Model ami Took for Geometric Desi^. 
These techniques can also be adapted for trse in modifying an existing curve, whether 
it was generated in the usual way or via one of these fining algorithms. 

CURVING ON 

Well, tliere you have it: more than you probably wanted to know about NURB 
curves, plus some free code to boot. Look for a possible upcoming article on IVURB 
surfiices, and how NURB curves and surfaces can be used together for designing 
objects and controlling motion. 
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CAL SIMONE 


ACCORDING TO 
SCRIPT 

Properties and 
Prelerences 


On the way to implementing scripting support in your 
applications, you're bound to confront a variety of 
issues. In this column, HI give you some pointers for 
devising and testing property names and discuss the 
techniques for handling preferences through scripting. 

PROPERTIES 

In an application's scripting vocabulary, a property is an 
attribute of an object. Properties can replace variables 
in if and repeat statements, as well as in expressions, 
and a script writer nomialiy uses the AppleScript verbs 
set and get with them. Here Fll give some guidelines 
for coming up with human-language names for 
properties and testing the viability of those names 
within the overall natural style of the AppleScript 
language. 

It’s important that properties have names that users can 
easily become familiar with. Ideally, users should be 
able to refer to properties in a script the way they diink 
or speak about them. 

Don't start propefiy names with verbs. Starting 
property names with verbs leads to confusion when the 
property appears in the middle of a sentence. For 
example, naming a property disable call waiting leads 
to commands that don’t read smoothly: 

set disable call waiting to true 
if disable call waiting then .., 

This is somewhat clearer: 


In feet, in the above case, it would be even better to 
name the property call waiting and use an enumeration 
as its value type (for a discussion of enumerations, see 
my article ''Designing a Scripting Implementation” in 
develop Issue 21). The choices enabled and disabled 
allow grammatically correct sentences, as in the 
following; 

set call waiting to enabled 
if call waiting is disabled ... 

A little creative thinking goes a long way in making it 
easy for users to work with the language. 

The "the" test. AppleScript allows you to add or 
remove the word the almost anywhere in a script 
without changing the meaning of the script. Many 
script writers precede object and propert^^ names widi 
the word the to make their scripts easier to read. 
Writing your test scripts in this way helps you 
determine the degree to which your property names 
facilitate forming natural sentences. 

set the service to "America Online" 
if the priority is high then .,. 

Don't confuse attributes and actions. Sometimes 
setting a property can cause an immediate change on 
the screen. In deciding whether to use a property in 
this situation, a helpful rule is: When an aciioTj is 
initiated, use a verb; when an attrilmte changes (even if 
it produces immediate visible results), use a property. 
Another way of looking at this is if a visible change is 
immediate, it's OK to use a property, but if an action 
has a duration, use a verb. 

As an example, the following command causes an 
immediate change on the screen: 

set the font of the third paragraph to "Courier" 

Even though setting the foot property creates a visible 
change, the font is still an attribute of the text, not an 
action. On the other hand, naming a property or 
enumerator playing, as shown in the next two 
commands, is a poor choice, because playing actually 
initiates an action: 


set call waiting enabled to false playing to true 

^ , set [the] status to playing 

if not call waiting enabled ... i j r j ^ 


CAL SIMONE (AppieUnk MAIN. EVE NT, Inlernet molnevent@his.com) 
wonts your dictionory for the Webster dotobose, which wilt be 
used to help resolve human-name conflicts between diFferent 
applications and scripting oddifions. Hell be onolyzing the terms 


in your vocobubry against others in seorch of simibrifies and 
differences- Send your bete’ resources to Cal via AppleLink or 
the Internet. * 
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The playing enumerator value in the second command 
is fine for obtaining state information, but a status 
property should be read-only. Instead of creating a 
property to control an action, use a verb. Verbs such as 
play or start playing are better suited for actions, as 
shown here: 

play the movie "Wowie Zowie" 

start playing the movie '’Wowie Zowie" 

Note that the commands are play and start playing, 
not play movie or start playing movie. In an 
application based on the object model, movie would be 
an object class. 

The properties property. A properties property 
enables script writers to obtain all die properties for a 
given object in the form of a record by using a get 
properties construct. (I first suggested using records 
in this column in develop Issue 22.) The properties 
property can also he set with the set command. The 
sample properties property shown in Listing I can be 
included as a property of any object for which you 
allow the setting of more than one property at a time. 


Listing 1. A sample properties property 

{ /* array Properties: 5 elements */ 

h |5] */ 

"properties^', 

^ Prop', 

*reco', 

"Property that allows setting of a list 
of properties.^, 

re s erve d, singleItern, notEn ume r at ed, 
readWrite, reserved, 


Dim’t require the user to supply all the properties when 
setting the properties property — allow the setting of 
just one or a few^ properties. 

get the properties of the fourth paragraph 
— returns font, size, style, and so on 
set the properties of the fourth paragraph to -» 
{font:"Helvetica", size:14} 

PREFERENCES 

Developers use a variety of techniques to allow users lo 
set preferences through scripts. FI! describe three 
common and easily implemented approaches for 
dealing with preference properties in your application 


class. (These same approaches can be used to 
implement document settings or group properties 
for individual idijects within your application.) 

Seporate properties for eoch preference. 

Implementing preferences as individual properties 
works well when you have only a few preferences. For 
example: 

set the connect sound to "Shriek" 

set the receive folder to alias "HD:Drop Folder" 

If you have many preferences, it’s inefficient for the 
user to have to set each property individually. To solve 
this, you can implement your preferences as individual 
properties (usually in your vocabulary’s application class 
definition) and also include a preferences property, 
described next. 

A property that includes all the preferences. You 

can make a single preferences or settings property, 
which is a record that’s defined elsewhere in your 
vocabulary. To define the elements of the record, create 
a fake “class” in your vocabulary, preferably in your 
Type Definitions Suite, to serve as the definition of the 
element labels in a record definition. In the comment 
field for your “class,” be sure to document dearly that 
this is a record definition, not an object class. Listing 2 
illustrates this technique; for more information, see the 
section “Define Record Labels in a Record Definition” 
in “Designing a Scripting Implementation” in develop 
Issue 21. 

Lists and records are the two principal constructs in 
AppleScript that don’t lend diemselves to human 
sentence structure. They are, however, an integral part 
of the language and can occasionally help to make the 
script WTiter’s life easier. When you use a record to 
create a preferences property, it’s OK to stray a little 
ft-om .strict naturaLlanguage style. Of course, when 
referring to elements of a list or record, you should use 
natural-language style. 

As with the properties property described earlier, don’t 
require the user to set all the individual preferences at 
once. Allow the setting of just one or a few preferences 
at a time: 

set the preferences to 

{connect sound; "Shriek", 
receive folder;alias "ED:Drop folder"} 

A user can address individual preferences as if they 
were defined as separate application properties. To 
allow for varying user experience witli AppleScript, 
your application should always accept property 
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specifications for individual preferences using the 
technique described above, regardless of whether the 
user includes the qualifying phrase of the preferences. 


Listing 2* A sample preferences property 

/* First, define this application property. */ 
{ /* array Properties: 5 elements */ 

/* [5] */ 

"preferences", 

'Pref', 

■cprf, /* for "preferences class" */ 
"Property that allows setting some or all 
of your preferences.", 
reserved, single I tern, notEmoinerated, 
readWrite, reserved, 

•. • /* more reserved items */ 

/* more property definitions 

/* Later, in your Type Definitions Suite, */ 
/* create a fake class. */ 

{ /* array Classes: 1 element 

/* [ 1 ] */ 

"p re fe re nc e s re cord", 

'cprf’, 

"A record containing individual preferences’^, 

{ /* array Properties: 10 elements */ 

/* [ 1 ] */ 

"connect sound", ■CSND', 'itxt', 

"the name of the sound to use when 
connected", 

reserved, singleltem, notEnuinerated, 

/* [ 2 ] V 

"receive folder", 'HELD', 'alls’, 

"the folder to place files when received", 
reserved, singleltem, notEnumerated, 

{ /* array Elements: 0 elements */ 

} 


For example, both of the following statements should 
be allowed: 

set the receive folder of the preferences to -« 
alias "HD:Drop Folder" 

set the receive folder to alias "HDsDrop Folder" 

Multiple "group'' properties for grouping 
preferences. If you have many preferences or want to 
group the preferences according to similar functionality^ 
such as those often found in multi paneled dialog boxes, 
you can create separate properties for groups of 
preferences or settings (using the record definition 
technique just described). The properties can reflect 
the groupings youVe set up in your graphical interface: 

set the compiler preferences to 
{warnings included:true, 
default integer size:short integer} 

set the drawing settings to ^ 

(pen size:{1,2}, shape:circle) 

A user addresses an individual preference by including 
in the object property specification the record that die 
preference is an element of, as follows: 

the pen size of the drawing settings 
set the shape of the drawing settings to 
rectangle 

set the default integer size of the compiler 
preferences to short integer 

PARTING WORDS 

Following these guidelines in implementing seriptability 
in your applications makes it easier for users to write 
scripts. Although they may seem like small points, ids 
the details that mean the difference betw^een frustration 
and smooth sailing for the scriptwriter. Remember to 
think about the way a user would write or speak about 
accomplishing what they want to do. Until next time, T 
remain your obedient servant on the AppleScript front 
rU see you on applescript-implenientors@abs.apple.com, 
the mailing list for seriptability. 


Thofiki to Eric Gundrum, Jon Pugh, and Derrick Schneider for 
reviewing this column." 


ACCORDING TO SCRIFTT^ PROPERTIES AND PREFERENCES 






Using C++ Exceptions in C 


Exception handling in C++ ojfers many advantages over eiTor handling 
in C Using the techniques outlined here^ you can implement C++ 
exceptions in your C code without a lot of effort The payback is 
streamlined debugging that can result in more efivr-jree code. When 
your prog^*am encounters erro?% it jumps to the appropriate error- 
handling sectio?t rather than dealing with the error locally. This 
simplifies your design and helps you concentj^ate on the notynalflow of 
control Centralized etror handling also makes it easier to improve 
your reporting and feedback mechanisms iniTementally. 



AVI RAPPOPORT 


I wrote a few little XC'MDs in C and after the fifteenth crash of the day^ I decided 
that rd better add some error handling. So 1 looked at Dartmouth X(]MDs, but I 
wasn’t impressed. Each check for an error meant another indentation in the code, 
and T was worried about disposing of handles correctly as I passed errors up the call 
chain. Since Vd been looking at a lot of C++ lately, I wondered whether I couldn’t use 
part of the C++ exception-handling mechanism to avoid problems in my code. It 
worked pretty well, so I thought Ed share my results. 

For part of tny solution, I used some Metro we rks macros. Metro werks has graciously 
alloM'ed these helpful exception and debugging source, header, and resource files 
to be included on this issue’s C]D, so you can use them without purchasing its 
Code Warrior CD. d'he files contain macros that provide convenient tools for 
implementing exceptions and tlchugging signals, as well as an aiert resource that can 
provide information during debugging. 


Although IVe used C++ exception handling in my C code with great results, Fd like 
to offer you one word of caution before you use them. Realize that C++ is not strictly 
an extension of C; as a result, in some cases it’s possible that the program may not 
behave as you think it should. 


BASIC ERROR-HANDLING REQUIREMENTS 

All programs must respond to system and subroutine failures somehow. For example, 
many Macintosh Ti^olhox routines remrn a variable of type OSErr, while others 


AVI RAPPOPORT has degrees in medieval 
studies and library/inFornnation studies, so she 
feels well qualified to work in ihe Macintosh 
softwore industry. In her job os user advocate and 
pubitcotions coordinator at Metrowerks, she spent 
her time documenting PowerPlant, making 


conference calls, and frantically trying to check 
CodeWarrior CDs before they were burned. Avi 
now works of StarNine as product manager for 
messaging products. She lives In Berkeley, 
Californio, with her Mac/Web scripter husband 
and their four-yeor-old son — oil BMUG members. * 
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require char you call Toolbox routines (such as MemError and ResEiror) to retrieve 
the error, IF yon ignore system and subroutine failures, your program is practically 
guaranteed to crash. 

Good error handling allows you to cope with many kinds of problems- Your checks 
can trigger other code that deals with the problem (for example, by freeing memory). 
During debugging, error checking should notify you that something has gone wrong. 
And since you can’t, unforninately, catch all die bugs during testing, you must also set 
up an error-reporciJig mechanism to notify your users when something has gone 
wrong. In the worst case, your error handling should at least ensure that your 
program exits gracefully, without losing or corrupting user data. 

THROWING EXCEPTIONS 

The -^\nierican National Standards Institute (.ANSI) has defined a mechanism for C++ 
compilers that allows code to ‘‘throw” exceptions. V\^en the compiler encounters a 
throw statement, it jumps to the nearest catch statement. (The “nearest” catch 
statement is the one associated with the current try statement, whether it’s in the 
current routine or forther up the call chain.) d'he catch statement can deal with the 
error, pass it up die call chain, or both. A throw statement should appear only widiin 
a try or catch statement or in code called from within a try statement. Listing 1 
shows these basic components. 


Listing Throwing exceptions 

OSErr theErr = noErr; 

// Try block, 
try { 

//Do something. 

//If error, throw an exception, 
if (theErr J= noErr) 
throw (theErr)j 

} 

// Catch blocks, 
catch (OSErr theErr) { 

//Do something with the error. 

> 

catch (. - -) { 

// Catch anything else. 

} 


As shown in Listing 1, exceptions are dealt with in catch biocks, which take an 
appropriate action depending on the error. For serious errors, this means cleaning up 
and temiinating the program. For less serious errors, the catch block could continue 
without making a fuss, or make changes based on the error and again call the routine 
that threw the error; sometimes you might want to thrown a more generic error, w hich 
is caught and interpreted in a higher-level catch block. I also recommend using the 
Aletrowerks signal macros (described later) within your catch blocks to help you 
locate errors during debugging. 
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The three dots in catch (,,*) are actually in the code; the other such dots thot 
appear in these listings are ellipses representing code that isn't shown.* 

When carefully designed, C++ exception handling in your program can deal with 
problems at an appropriate leveh As yon may already have guessed, this feature is 
bodi powerful and dangerous. 'The advantage is that you don't have to mess around 
widi returning errors for every routine or indenting deeply. However, if you allocate 
memory, you must be careftil to dispose of it at the right time or it will cause a leak. 

ADDING EXCEPTIONS TO YOUR CODE 

To add C++ exceprions to your code, you must do die following: 

• Force the use of die C++ compiler. 

• Create a top-level excepdon handler in your main routine. 

• Define try blocks and catch blocks, and call tlirow at appropriate times. 

• Add die C++ library {CPlusPlusJib, (TinsPlusA4Jib, or MWCRuntime.Lib) 
to your project. 

The jMetrowerks macros diat you'll see in the cotie that follows make implementing 
exceptitm handling much easier dian it would he otherwise. I'll talk about them later. 

USING C++ 

To use C++ exceptions, you have to force die use of die C++ compiler. In Metrowerks 
Code Warrior, the easiest way is to select the Aedvate C++ Compiler checkbox in the 
C/C++ I .anguage panel. You should also make sure that the Enable C++ Fxcepdons 
checkbox is selected, because it enables throvdng exceptions radier than direct 
destruction (one of those weird C++ things). An alternative way to invoke the 
compiler is to change the extension on your source code files to ^.cp” or by changing 
the darget panel preferences; however, the checkbox method is the easiest. 

C++ is stricter about automatic parameter conversion than C, so selecting die MPW 
Pointer Type Rules checkbox in the C/C++ Language panel avoids a bunch of errors 
{it forces die compiler to allow some implicit char* casts). But you'll get errors for 
other parameters and return values, so you have to dean them up as indicated by the 
compiler. For example, the following is an error message returned by a C++ compiler: 

HC2RTF,c line 224 textLen = strlen{textstring); 

Error : cannot convert 
'unsigned char to 
'char *■ 

To fix diis problem, you can change the code to 
textLen = atrlen((char *) textString) 

The CodeWarrior C++ compiler puts special C++ information into function names 
(this is called fiame mangling). C doesn’t do this, so header files for C functions should 
be surrounded by #extem statements to tell die compiler not to mangle diese 
names (see Listing 2). The Macintosh Toolbox header files take care of this already. 

CREATING A TOP-LEVEL EXCEPTION HANDLER IN MAIN 

In your main IcKip or function, you should specify the top-level exception handler. 
Tlus should catch serious errors, report them, and exit gracefully. Listing 3 shows the 
simplest possible excepdon handler (which you'll understand better as you read on). 
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Listing 2. PrevenNng name mangling 

#ifdef _cplusplus 

extern "C" { 
fendif 

long FindBreak{char* buffer, short len)j 
// More declarations here 


iifdef _cplusplus 

} 

iendif 


Listing 3* Simple top-level exception handler 

pascal void main(XCmdPtr parainPtr) 

{ 

long oldA4 = SetCurrentA4(); 
try { 

CreateFile[paramPtr ); 

WriteFile(paramPtr ); 

} 

catch (*. *) { 

ReportError(’'\pSerious error occurred.”) 
// XCMDa do not have to use ExitToShell. 

} 

SetA4(oldA4); 

} 


DEFINING TRY BLOCKS 

When you use a try statement, it tells the compiler that the following code might 
have exceptions thrown in it. All fimctions that throw exceptions must be within a try 
block, cither Ln the current function or in a calling function, lt"s pretty easy to set up 
try blocks before catch blocks. This is good, because you do have to do it: any throws 
that aren't caught will automatically abort the program, 

DEFINING CATCH BLOCKS 

You should have catch blocks for each error type. So, for example, you might define 
catch (OSErr dieErr), catch (errStmct errRecord), and catch (Str255 theErr). 
You should also have a generic catch, catch (...), which doesn’t have any parameters, 
to catch exceptions of all other types. Although it’s better to use typed catches that 
handle specific errors, always add at least one generic catch and have it signal an error 
with an alert or break to the debugger. This vnl\ help you catch exception mistakes 
during your debugging and testing phase. Listing 4 shows examples of these types of 
catch blocks. 

The compiler automatically routes the error to the appropriate catch statement, 
depending on the parameter passed to the throw statement In Listing 4, both the 
StringPtr and OSErr types are caught specifically, after which tliey’re reported. The 
OSErr catch rethrows the error as well. Any other types of errors are caught by the 
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generic catch, which c^Us a signal macro to display a message and then exits the 
program. 


Listing 4. Specific and generic catch blocks 
catch {StringPtr errString) { 

// If HandleError throws, it will be caught above this catch, 
HandleError(errString); 

> 

catch (OSErr theErr) { 

Str255 errString; 

C onve rtE r rToString(theErr, e rr Strin g); 

ReportError(errString); 

throw (theErr); // Rethrow to handle error, 

} 

// Forces the application to quit after the message, 
catch (-. -) { 

SignalPStr_("\pUntyped error occurred in prefs,") 
ExitToShellO; 


You can, and often should, continue after catching an error. For example, after a disk 
full error, you should allow the user to choose a different volume. Note chat the 
program will continue after the catch block, rather than in the Icjcation where the 
exception w^as thrown, 

MOVING DEEPER — HANDLING EXCEPTIONS IN THE 
CALL CHAIN 

Many of your low-level routines may call the Macintosh Toolbox or otherwise 
interact with the Mac OS. They should throw an exception if there’s an error, as 
shown in Listing 5, 

So w here do you catch these exceptions? Remember, they percolate up the call chain 
until they find a catch statement, so you don’t have to take care of them in tlie 
immediate calling fimction (unless you’ve allocated memory or done other things that 
need undoing). When you catch tliem, you can, and sometimes should, throw the 
error again. You can either report errors in mid-level routines or rethrow^ them up to 
a higher-level error reporting mechanism. 

In addition to these catch statements, be sure to add a catch statement in circumstances 
where you need to do any of the following: 

• Dispose of handles and otherwise deallocate memory. 

• Shut dovm something you started in the try block, such as opening a file. 

• C h an ge the error th rowm. 

For your own ftinctions, you should throw errors in situations that can cause serious 
problems or crash the machine. For instance, if you’re providing a function that 
accesses a variable-length array that contains 16 members and the caller asks for the 
17th member, you can throw' a range error. There’s no hard-and-fast rule about when 
to put the error checking into a function and when to require it before calling— it 
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Listing 5. Throwing exceptions for Macintosh Toolbox errors 

void MakeMyResFile(Str32 fileMaine) 

{ 

CreateResFile(filename); 

// Could also use the Metrowerks ThrowIfEesError_ macro, 
err = ResError(); 
if (err <> noErr) 
throw (err); 

// Continue with execution. 


// Call the function, 

MakeThisFiieO 

{ 

try { 

MakeMyResFile(thisFile); 

} 

catch (OSErr theErr) { 

if (theErr == dupFNErr) { 

// Do something; file already exists, 

else 

throw (theErr); // Rethrow the error, 
} // End catch statement. 


depends on tlie situation. For example, if you're calling a function inside a tight graphics 
loop only and yon want speed, yon can probably check the parameters sufficiently in 
the calling function. However, if you have a utility routine that's called from several 
sections of your code, adding error checking mil help you remember its requirements, 
such as parameters, memory, and other system states, to avoid problems later on. 

Handling exceptions in libraries is tricky because you don't know much about the 
calling program, lltink carefully about what you should report to the user and what 
you should simply return to calling functions. 

As your programs become more sophisticated, you can start working around certain 
errors — for example, by using temporary memory when the application's heap is full. 
You'll also need to design interactive error reporting, allowing your users to take 
action (such as unlocldng a locked disk) when they can. 'Fhen your application can 
continue properly 

EXCEPTIONS AND DEBUGGING WITH THE METROWERKS 
MACROS 

The Metrowerks PowerPlant UDebugging and UException files, included on this 
issue's CD, provide convenient tools for throwing common exceptions and alerting 
you during debugging. To use them, put the folder in your project folder, add the 


USING €++ IXCEPTIQNS IN C 


83 





sources and tlie “PP DebugAlerts.rsrc” resource file to your project, and include the 
headers in your source files. 

The UException.h file includes macros that automate common exception ccmditions. 
The UException.cp file includes an abort function. The UDebugging.h file defines 
some macros that make locating problems easier by allowing you to specify a signal^ a 
debugging string displayed when die macro is invoked. 

If your proiect mcludes an ANSI library you don'l need \o add UException.cp. 

The abort function will conflict.* 

SETTING GLOBAL VARIABLES FOR DEBUGGING 

You need to set the global variables gDebugEhrow and gDebugSignal in UDebugging.h 
to specify the debugging actions for throws and signals. By default, they’re set to do 
nothing at all. Other options include displaying a dialog, dropping into die source- 
level debugger, or dropping into the low-level debugger. 

To activate die macros, l>e sure to define Debug_Signal in your [^recompiled header 
or UDebugging.h. 

The following are the global variable options: 

• debugActiDn_Nothing — Do nothing. 

• debugActic>n_Alert— Display an aleri box wuh an exception code {described 
later), filename, and line number where the throw or signal was made. For 
this to work, you must include the file “PP DebugAlerts.rsrc’’ in your 
project. 

• debugAction_Source Del nigger— Break imo the source-level debugger. For 
the Metrowerks source-level debugger, execution will stoji with the arrow 
pointing to the line containing the throw statement. I'he exception code 
isn’t displayed. You can check the display of variidile values in the source- 
fevel debugger for that information. (IVe tested this w ith the Metrowerks 
debugger only.) If you aren’t running under the source-level debugger, 
debugAction_SourceT^ebugger will break into the low-level debugger on 
PowerPC processor-based machines, but might crash on 6H0x0 systems. 

• debugActiDn_EowEevelDebugger — Break into AkesBog and display the 
exception code as a string. In Macs Bug, the console will display two lines: 

User Break at rou ti/je + offset 
except! Oil code 

Note that if you don’t have a low-level debugger insmiled, your program wall 
crash with an imimplernented trap error if it tries to break into the low-level 
debugger. 

THE THROW MACROS 

UException.h defines several useful macros that automatically perform tests and 
throw' exceptions if a test failed. It also defines a type, ExceptinnCode (a long), and 
two standard exceptioiis, eiT_AssertFailed ('asrt') and err_NilPointer (’nilP'}, w^hich 
are treated as type Except!onC(jde. Here are the throw macros: 

• d'hrowIf_(^i?.rt^) — Throws an exception if test is true, where test is a Boolean or 
the result of a Boolean condition. The exception code wall be err_AssertFailed. 

• Throw'IfNot_(fr.^r) — Throws an exception if is false. The exception code 
will be err^AssertFailed. 
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• ThrowIfOSErr_(^^/T) — l^hrows an exception if isn’t equal to noErn 

• ThrowOSErr_ (f/r), FailOSErr_ (e?r) — Throws an exception with m’ as 
the exception code. 

• ThrowIfNULL_(/?rr), Throw[fNiI_(/jrr), FaiINiL(p^^') — If prt* is NULL (or 
nil), throws an exception with err_Ni I Pointer as the exception code, 

• Th r()wlfMemEr ror_(} — Ca 11 s the Toolbox routine Mein Er r) r and thr()ws 
an exception if it retunxs a resul t that’s not equal to noErr; the MemError 
return lieconies the exception code. 

• TlirowI{MemFail_(p) — Throws an exception if p (a pointer or a handle) is 
nil. The MemError routine is used to check the success or failure of the last 
Memory Manager calk If MemError returns a result tliat’s not equal to 
noErr, the exception code is set to the return value of the MemError calk 
If MemError returns noErr, the exception code is set to memFullErr, a 
constant defined by Apple. 

• ThrowlfResError_() — Calls the Tooll)ox routine ResErrnr and throws an 
exception if it returns a result that’s not equal to noErr; the result becomes 
the exception code, ResError is used to check the success or failure of the 
last Resource Manager calk 

• ThrawIfResFaiU(/j) — Throws an exception if h (a handle to a resource) is 
nil. If ResError returns a result that’s not equal to noErr, the exception code 
is set to that result. If ResError returns noErr, the exception code is set to 
resNotFound, a constant defined by Apple, 

You can use all of the macros within iTelse clauses, as they’re designed to be self- 
contained. For example: 

if (err 1= fnfErr) 

Throw!fOSErr_(err); 

THE SIGNAL MACROS 

UDebuggingdi defines macros for raising signals, also known as assorts, lEese will 
stop die execution of the program and report errors. You can use them to check for 
nil pointers, out-of-range offsets, excess length, division by zero, and other problems. 
If you remove die definition of Debug_Signal, the entire set of macros is converted to 
white space and takes no runtime overhead whatsoever. 

The macros are defined to check gDebugSignal for the action to take on execution, as 
described previously. 

The following are the signal macros: 

• Signal PStr_(pj?r) takes a Pascal string argument. The string can be a literal 
Pascal string (in double quotes beginning with \p) or a StringPrr variable 
(and its variants, such as Str255), 

• SignalCStr_{i:jtr) takes a literal C string argument. The string must be 
a literal (text within double quotes) and can’t be a char*. Because the 
underlying Toolbox routines take Pascal strings, the Signal PStr_ macro 
is more eificient. 

• Signallf_(ter?), Signal I fNot_(fe,Tf) each take a Boolean condition as an 
argument and raise a signal depending on whether the condition is true 
or false, 

• Assert_(^er/) is a synonym for SignalI£Not_(fe'jr), 
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STRESS REDUCTION WITH EXCEPTION HANDLING 

C++ exceptions and these Metrowerks macros make error handling reasonably easy to 
add to most programs. With a little thought, you can design a clean structure for 
dealing with Mac OS errors and internal errors — a structure that^s easily extensible 
to new code. You can avoid stress during testing by adding signal macro calls for 
common errors throughout your code. TheyVe much easier to debug than system 
crashes. And yes, thank you, my XCMDs are much better now! 


RELATED READING 

• For a more in-depth exo mi nation of exceptions in C++, consult the article "Try 
C++ Exception Handling" by Kent Sandvik (Aloclech Magazine, October 1995). 
For another view of C exceptions^ see "living in an Exceptional World" by Sean 
Parent in develop Issue 11. 

• For information on the return values of Macintosh Toolbox routines and the error 
codes, see the Imide Mocmtosh series, Mocmtosh Progrommer's Toolbox 
Assistonft and THINK Reference. You can also look ot the header file Errors, h. 

Because C has no objects, when you read these publications, you can ignore all 
discussions of object throwing, exception objects, construction, and destruction. 


Thanks to Greg Dow, Pete Gontier, Tom and personal patience, and to Pete and Tom for 

Lippincott, and Jon Wdrte for their C++ wizardry reviewing this article * 
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MPW TIPS AND 
TRICKS 


Last issue’s column discussed various ways of using 
ToolServen I looked forward to deeper integration of 
MPW scripts into other development systems, in a 
stirring plea that must have brought tears to the eyes of 
many an overly sensitive reader. In this column, 1*11 
show just how self-fulfilhng a prophecy can be: 1*11 
explain how to use a generic TooiServer plug-in 
compiler with the popular Metrowerks Code Warrior 
development system. 

BEYOND THE WORKSHEET 

CodeWarrior already comes with TooLServ^er support 
in the form of an integrated Worksheet window, similar 
to the MPW Shell Worksheet. Simply choose Start 
TooiServer from the Triols menu and you can issue all 
kinds of shell commands. It’s like a miniature MPW 
Shell inside CodeWarrior. WTiat more could you ask for? 

Ten bonus points for reading skills if you could tell that 
that wasn’t really^ a rhetorical question. The Worksheet 
is useful but it fulls short of full integration. True, you 
can execute a Make command from Code Warrior’s 
Worksheet, but it would he even better to integrate 
xMPW tools and scripts into the default CiideWarrior 
build sequence. 

Let’s say you have a SOxM build — that is, you’re using 
IBAl’s System Object Model as implemented on the 
Macintosh in the form of ^^SOMObjects forMacOS™”, 
Before too long, it*s likely that the current preprocessing 
approach to SOM will be just a fading (though still 
traumatic) memory, and that CodeWarrior and MPW 
will have direct-to-SOiVI compilers. For now, though, 
building with SOxM requires running MPW tools and 


Using TooiServer 
From CodeWarrior 



scripts to generate include files which are then 
processed by the C or C++ compiler. 

Error prevention is one of the basic principles of user 
friendliness. You can invoke the SOM compiler frcjm 
a makefile and nm it in the CodeWtrrior worksheet 
before you build, but if youVe like me, short-tenn 
memory loss from a misspent youth will cause you to 
forget to nm the makefile from time to time, leading to 
his^^arre errors and gratuitous hair-tearing behaviors, 
MPW makefiles provide another rich source of errors 
by requiring you to track your own include files. 

It’s more convenient to simply give the single menu 
command Make than to bring up the Worksheet, enter 
“Bui Id Program MyBuildFile’^, wait for the build to 
finish, and then give the Make menu command. One 
coLiid only wish that CodeWii trior had a built-in SOM 
compiler. 

A BUILT-IN SOM COMPILER (AND MORE] 

Thanks to CodeWarriork new plug-in compiler 
architecture (available starting with CW7), you can add 
build rules that invoke TooiServer scripts automatically 
to compile “.idl” files, t)r any other type of file. I’ve 
created a generic TooiServer plug-in for CodeWarrior 
(found on this issue’s CD) tliat allows you to set up 
different command lines for different filename 
extensions. It will automatically track include files as 
well, if y(JU want it to. It should be pcjwerfiil enough for 
most applications, but if you need something different, 
you can take the source code and hack it endlessly to 
your own nefarious purposes. 

To in.stall the plug-in compiler, put the compiler file 
TbolFrontEud into the Compilers folder of the 
CodeWarrior Plugins folder of your CodeWarrior 
application folder, and die preferences file ToolFrontEnd 
Panel into the Preferences folder of CodeM'arrior 
Plugins. To set it up, first decide which filename 
extensions you want to nin through TooiServer; in this 
example, we’ll be doing the “.idl” files used by SOM. 
Give the Preferences menu command in CodeWarrior, 
go to the Targets panel, and attach the ToolFrontEnd 
compiler to source files of the appropriate type and 
extension. 

Finally, go to the new^ ToolFrontEnd panel in 
Preferences and enter the command line you want to 


TIM MARONEY depends on calcium for his struefumi integrity 
and potassium for the generation of axonic spikes in his nervous 
system. His recent reading Includes Mysticism and Philosophy by 
W. T. Slace, Popper Seiecflons edited by David Miller, Seth^. Ood 
of Confusion by H. Te Velde^ Abrahadahro by Rodney Orpheus, 


Hathor and Thoth by Dr. C. J. Bleeker, Making Monsters by 
Roc hard Ofshe and Ethan Watters^ ond Soul Music by Terry 
Pratchett. A thoroughgoing nommolish Tim doesn't believe in 
either tobies or noturo! laws, but his contract work at Apple 
remains stubbornly limited by his desk and by the flow of time " 
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execute for files of this extension. The ToolFrontEnd 
panel is shown in Figure 1. Like aU software, this is a 
work in progress, so it may look slightly different by 
the time it reaches you. 

The pop-up menu allows you to enter different 
commands for different filename extensions. Bind each 
extension to the ToolFrontEnd compiler from the 
Target panel. 

The Script Include File will be executed before your 
command line. This lets you set up variables and aliases 
that may be useful for your scripts and tools. The 
same include file is used for all filename extensions. 

The include file can be anywhere in the project’s 
access paths. Here Vm using an include file named 
“cwtsinclude,’’ which sets up a few handy variables. 

You don’t need to specify any include file if you don’t 
want one. 

Your source file can be preproccsscd to find include 
files, Fve provided a default preprocessor that deals 
with #include specifications. You can add other 
preprocessors — see the documentarion and sample 
code that come with the softw'are. Each include file wdl! 
be added to CodeWarrior’s internal list of dependencies 
for the source file, so die source file will automatically 
be rebuilt when an include fi le changes. If you don’t 
want to scan for include files, choose None from the 
pop-up menu. 

All include files should be in the ClodeWarrior project’s 
access paths. The project’s access paths will be combined 


into the IncludeFiles variable, prefixed with the Path 
Parameter shown in the panel. This variable is available 
to all scripts executed from the plug-in. 

All commands will he executed in the TtiolServer 
context, so they’ll use any startup scripts you’ve 
installed. See the notes from last issue’s column 
about minimizing dependencies, though; all your 
requirements should be fulfilled by files you explicitly 
execute or by the Script Include File specified in the 
panel. Otherwise you’ll run into configuration 
synchronization problems when restoring archived 
builds or sharing sources with your team members. 

When the plug-in compiler executes scripts, ToolServer’s 
current directory will have been set to the folder 
containing the project file. The following variables 
will be set up: 

• (IncludeFiles} — the parameterized include path list 

• (ProjectFolder) — the full pathname of the folder 
containing the current project file 

• {SourceFile} — the full pathname of the source file 
being compiled 

• {SourceFileStem] — the root or stem of the 
name of the source file (for instance, the stem of 
**jVIyPanels,idl” would be *^MyPanels”) 

Generally speaking, you’ll probably want to create a 
front-end script for the plug-in compiler, rather than 
enter a raw MPW command line in the panel. This 
allows you to specify any number of parameters, 


Apply to open project. 


PPC Linker 

PPC PEF 

PPC Project 


iP 


1, Script Include File: 


cuitsinclude 


File Eutension: 


.idl 


Zl 


The ToolServer Command Line: 


ciiisomc "{SourceFile}" -o lObJects: {IncludeFiles) 


Include File Scanner: 
Path Parameter: 


^include 
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[Factory Settings] [Reiicrt Panel 


Cancel 
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Figure 1. The ToolFrontEnd preferences panel 
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redirecdons, and .so on in a script file without worrying 
about the text editing limits in the modal dialog. The 
command line you specify can be up to 255 characters 
long. ITe SOM compiler has a lot of options, so IVe 
put all the ones I use into a script file named '‘cwsomc.” 

All diagnostic output will appear in die CodeWarrior 
error window. All standard output will he ignored. 
Internal errors in the plug-in will appear as alerts. 

Due to a limitation in the current plug-in API, 
CodeWiirrior doesn’t know about dependencies 
involving compilers that put out source files. While the 
SOM compiler will emit, for instance, a ‘^xh” include 
file that will be included by a file later in the build 
process, there is currently no way for CodeWarrior to 
know that the file depends on the '^idl” file from 
which die ‘^.xli” file was genenited. This will be fixed in 
a future version of the API, and Fll add functionality to 
the ToolFrontEnd plug-in to support this feature when 
it becomes available. For now, since CodeWarrior 
compiles files in the order they appear in the project 
file, just put “.id!” files above “xp” files. 

UNDER THE HOOD 

Source code is provided with ToolFrontEnd, so you can 
get a detailed peek at its insides and mutate it to your 
own needs. A quick overview may be useful here, though. 

ToolFrontEnd sends commands tolholServer in the 
form of Apple events, as described in last issue’s column. 
It builds a coiiunand in memory that is a short inuldline 
script with semicolons separating the commands. The 
last conunand of this script is the one you typed in 
the preferences panel. At the start of the script are 
commands that set the four variables described above. 
The diagnostic output is extracted from the 'diag' 
parameter of the reply Apple event returned from 
ToolServer, and the error code is extracted from the 'stat* 
parameter. All this is done using a slighdy modified 
version of the sample code for communicating with 
SourceServer that I provided in this column in Issue 25; 
die Apple event conventions of SourceServer and 
Tool Server are much the same. 


The plug-in was built by starting with the sample code 
prcwided with CodeWarrior. I didn’t have to make any 
large-scale changes to the structure — Metrowerks 
deserves kudos for the quality of their sample code and 
their clean API. There are two code modules to be 
built, one for the preferences panel and one for the 
compiler itself. Liluary routines are provided for 
common operations like registering a dependency and 
getting a stored preferences record. The sample compiler 
already contained an include file parser, which I broke 
out into a separate module to allow customization for 
different file types. 

THE BEST OF TWO WORLDS 

Though IVe shown just one example, many different 
things can be done with the ToolFrontEnd phig-in. 

One of my friends is using a third-party version of the 
UNIX"" tool yacc (Yet Another Compiler-Compiler), 
which is dehvered as an MPW tool. Thanks to diis 
plug-in, he no longer has to switch between the MPW 
Shell and CodeWarrior constandy You could also 
define your own macro language to preprocess your 
source files, or add your own original compilers. And of 
course, using Tool Server scripts from the compiler is 
fully compatible with using the (CodeWarrior ToolServer 
Worksheet window for odier tasks such as installing 
software. The Worksheet is also useful for testing and 
debugging scripts you’ll use with ToolFrontEnd. I 
haven’t provided a linker plug-in, but the API is similar 
and the compiler plug-in could easily be adapted to 
this purpose. 

With ToolFrontl^nd, the friendliness of CodeWarrior 
and the power of MPW celebrate a kkros gamos (or 
sacred union, if that’s Greek to you). The fruit of this 
union is an all-in-one development environment from 
which you can execute your entire build process, no 
matter how complicated, without changing contexts 
or inviting errors. Those whose souls are devoid of 
romance may prefer to contemplate the consequences 
of increased productivity for their next performance 
review — in either case, enjoy in good humor and 
good health! 


Thanks to Rick Mann and Greg Robbins for reviewing this 
column.* 
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Country Stringing: Localized Strings 
for the Newton 


Newton products are curre?itly available localized for Ejiglish^ French, 
German, and Swedish. Th'us, to take full advantage of the market, 
Newton applications must be developed for four languages. As of 
Newton Toolkit version 1.5, there’s a mechanimt for localizing strings 
at compile tme but no builtrin support for organizing all the categories 
of .strings across the different languages (unlike on the Macintosh, 
where you can use resources). This article presents a couple of ways to 
organize localized strings in your Newton application. 



MAURICE SHARP 


Until Newton Toolkit 1.5, developing an appliauion for Knglish, French, German, 
and Swedish required four different application projects or many skanky contortions* 
This was tedious, to say the least, Imt necessary for those who wanted to take full 
advantage of the w^orldwitle market Inr Newton products. 

Newton Ibolkit 1.5 provides support (with the SetLoealizaticmFraine and LocObj 
calls) for localizing your applications from just one project. But this is useful only at 
compile dmc, and it doesn’t provide an infrastructure lor organizing and categorizing 
the localized ohjecLs* In other words, you can have different strings for four locales, 
hut how you keep track of what strings you have and w hich ones need localizing is up 
to you. xMadntosh developers don’t have this problem [lecause all strings can reside in 
resources; changing the strings in the resources changes them in the applicatitm. 

ddiis article presents two ways to organize your localized strings. Both methods are 
meant to be used at compile time, but there’s also information on changing strings at 
run time. Before reading this article, you should be familiar with the information in 
the Newton Pro^anmier^s Gtnde on locahzing Newton applications. 


STRINGING YOU ALONG WITHOUT RESOURCES 

In a Macintosh application you can keep localized strings in the 'STR#' resource of 
the resource fork. This isn’t an option in a Newton application for two reasons: 
ResEdit doesn’t directly support Unicode strings, and, more important, a Newton 
application doesn’t have a resource fork. AJl your strings have to reside somewhere in 
your application package. 


MAURICE SHARP is a truly multinational 
person. He was born in England, naturalized to 
Canada, and now lives in California. He hopes 
to visit the United States someday os well. His 
multinational bockground makes him a bit 
psychotic when it comes to beer. He^s never sure 


jF he should order it warm or cold, or [ust have 
water. This is why he prefers sake. Maurice is one 
of the orfginol members of Newton Developer 
Technical Support and is still there (remember, we 
said he was a bit psychotic).* 
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A first cut at a solution to the problem of how to organize localized strings in your 
Newton application would be to have a viewSetupFormScript or TextSetup method 
(where applicable) that sets a particular string based on some application-global 
setting. This solution has several disadvantages, such as spreading localized strings 
throughout the code (resulting in multiple copies of strings) and requiring all strings 
for all countries to be included. 


If you’ve programmed the Newton for a while, you might think of taking advantage 
of dead code stripping and using an if statement that switches on a compile-time 
constant. This would eliminate unused localized strings but is still awkward. 

The best idea is a technique that lets you keep all your strings together. You can do 
this by defining a frame in your Project Data with one slot per string that you want to 
localize. You can even use nested frames. For example: 


constant kUSStrings t- '{ 

AppName: "World Ready I", 


ExtrasName: 
HelloWorld: 
Dialogs I { 
OK: 

Cancel: 
Yes: 

No: 


"World I \ 
Hello World" 

"Cancel", 

"Yes", 

"No", 


} t 

constant kFrenchStrings := .,. 


In Newton Toolkit 1.5 and later, you can use this frame with SetLocalizationFrame. 
Unfortunately, there’s no specification for how' to build up die frame, which is essential 
CO organizing your strings in a sane way. Also, SetLocalizationFrame is meant only 
for compile-time localizations. With some extra effort you can organize the strings in 
a way that allows them to be localized at run time as well. As the next section shows, 
the key is using the Load command in combination widi a few constant functions. 


LINGUA FRAMA — CREATING THE LANGUAGES FRAME 

In the previous section, we defined a frame that can be used for each target language. 
Each of those target language frames can be nested into an outer frame, called the 
languages frame. Each target language subframe contains the localized strings in that 
language. These subframes can in turn contain otlier subframes, enabling you to 
group strings into logical categories such as strings used in filing, strings used in 
searching, and so on. Each of die frames at the top level of the languages frame 
must have tlie same structure. If you have a path in the USEnglish frame of 
Entries.Names.Phones.Home, that path will also need to exist in French, German, 
and any other languages your application supports. 

The overall structure of the languages frame is as follows: 

{USEnglish: { 

AppName: "World Ready!", 

Dialogs: { 

Cancel: "Cancel", 

OK: "OK", 

// ... and so on 


cpummr stiungiisig: locauzed strings for the newton 
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French: { 

AppNaiiie: "Pret pour le Monde r*, 

Dialogs! { 

OK: "0K% 

Cancel: "Annuler^, 

// ... and so on 

}. 

German: { 

AppName; "Welt Ready!", 

Dialogs: { 

OK: "OK", 

Cancel: "Absagen", 

// ... and so on 
J f 

// ... and so on 

} 

This is the format of the frame you would pass to SetLocnIizationFrame as well as of 
a constant that can be used in runtime localization- 'lypically, die languages frame 
would be kept in a text file or in your Project Data. The problem with this is that the 
frame is rather large, and adding or changing an entry in a language subframe can be 
difficulL Also, several entries are idendca! (such as the string for OK). 

A better solution is to separate the localized strings by category This article uses the 
target languages as the categories, though you could also employ similar techniques 
with other categories. Once the strings are split, you can use the Load command to 
assemble the languages frame. 

ITere are two main schemes for organizing the strings. One uses simple text files and 
w'orks on both the Mac OS and Wndows platforms. The other uses compile-time 
functions to read the strings from some other foniiat; on the Macintosh platform, this 
method can be useil tf> construct the languages frame from a resource file. We’ll look 
at each of these methods in turn. 

LOADING FROM TEXT FILES 

In die first scheme, you separate each language into a different text file. Remember 
that Load will return the result of the last statement it executes in the specified file. 
This means that each text file will specify one frame. Fur exanT|)le, the contents of 
your French text file might look like this: 

{ 

AppName: "Fret pour le Monde!", 

Dialogs: { 

OK: "OK", 

Cancel: "Annuler", 
if ... and so on 

} 

>; 


You could then modify your Project Data to build the localization frame: 

SetLocalizationFrame((French: Load(HOME & "FrenchStrings.f"|, ... 

It’s also helpful to have some string constants that can be used in multiple places. A 
good example is the string for OK, which is the same in some languages. To do this, 
you should load some general constants before constructing the individual languages 
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that make up the languages frame. So the overall process for building the languages 
frame would be as follows: 

K Load a file of string constants. 

2. Construct an empty languages frame. 

3. For each language, build the individual target language frame and add it to 
the languages frame. 

You only need predefined constants if yea aren't using obiect combination. 

Obiect combination, a feature that exists os of Newton Toolkit version 1.6, would 
solve the problem of multiple instances of o single string (such os "OK'').* 

7Le above description smells of an algoritlim. Since you can run NewtonScript at 
compile time, you can call a function to load a languages frame from text files (see 
Listing 1). The main crick of this function is that it uses the language symbol to 
create a pathname for Load. 


Listing 1, CreafeLonguagesFrameFromText 

global CreateLanguagesFrameFroinText{GlobalsFilePath, LanguagesSymArray) 
begin 

if GlobalsFilePath then 
Load(GlobalsFilePath)? 

local langFrame i“ {}; 

foreach sym in LanguagesSymArray do 

langFrame* (sym) := Load (HOME & sym & *’Strings,f; 
langFrame; 
end; 


You can define this function in a text file (say, WorldStringsi) that you add to your 
project. Note that you must compile this file before you load your international strings. 

You could use the languages frame directly as the argument to SetLocalizationFrame; 
however, as we’ll see later in this article, there are better ways to use the frame. 

LOADING FROM RESOURCES 

'Fhe second scheme creates the languages frame from a resource file. You can apply 
the methodology to other non-text file sources as well. To take advantage of the code 
below, you’ll need Newton Toolkit 1.6 or later. One important point: all of this code 
works only for Roman-based languages. 

To make Hfe easier, we’ll define a template in ResEdit that shows all the localized 
versions of a particular string. The template defines a resource of type TOC#’, which 
is loosely based on the 'STR#' resource (see Table 1). Because we’re using a template, 
the number of languages must be defined in advance^ we’ll choose 5 as a nice arbitrary 
number. You can find the TOC#' template in the sample code on this issue’s CD. 

You can now' use the 'LOC#' resource to enter all of your strings, grouped into 
categories that make sense to you. The advantage of this resource is that the path 
expression in the languages frame and all localized strings for that path expression are 
grouped together. 
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Table K The'LOC#' template 


lieiti Number 

Label 

Type 

1 

NumStrings 

OCNT 

2 

* + ■»** 

LSTC 

3 

path 

CSTR 

4 

English 

CSTR 

5 

French 

CSTR 

6 

German 

CSTR 

7 

Other 1 

CSTR 

8 

Other2 

CSTR 

9 

***** 

LSTE 


You may be wondering why the 'LOG#' template contains an English string. If you 
use LocObj, the first argument is a string that’s taken as the English localization. For 
the case where youVe only localizing at compile time, the English string is redundant. 
But if you want to localize at run time, you’ll need the English string around. 

If you’re familiar with the resource calls in the Newton Toolkit, you will have spotted 
a potential problem: there’s no way to query for the available resource IDs of a 
particular resource. The basic solution to this problem is to try reading a resource 
and CO catch the exception that the Newton Toolkit throws if the resouixe isn’t 
present. Unfortunately, iterating through aU possible resource IDs while catching 
exceptions takes several minutes. 

So we impose these restrictions: there can be any number of 'LOG#' resources but 
they must be numbered consecutively, and the first resource ID must be either 0 
(because programmatically generated resources are likely to start wnth 0) or 128 
(because those created in ResEdit will start with 128). The code in Listing 2 generates 
an array of resources of a given ty|3e based on these criteria. 

Gnce you have an array of 'LOG#' resources, you need to parse these resources into 
New'tonScript path expressions and strings. The code in Listing 3 gets all the TOC#' 
resources and generates a languages frame. 

Unlike the text method, the resource method has to assume a certain number of base 
languages. The first thing tlie code does is to check that there are exaedy five language 
symbols. If not, the code throws an exception. The result k a typical Newton Toolkit 
error dialog with the string specified in the code. 

In reality, we could be a bit more forgiving. The code won’t create entries in the 
languages array for items that are empty strings. So if a developer w^erc careful not to 
fill out entries for particular languages, the restriction could be relaxed to m imre than 
five languages. You could also make the code a bit more complex and just not add 
strings for undefined languages. 'ITiis is left as an exercise for the masochistic reader. 

An even better approach would be to create some other resource (say LOCi') diat 
contains information on how many languages are defined by the TOG#’ template 
and the language symbols. It would require slighdy more complex code for 
GreateLanguagesFrameFromRsre, but it would provide more flexibility later on. 

The GD contains modified code that uses an 'LOCi' resource. 

As you can see, this is considerably more complex than the ftmetion used for text files. 
Also note that this methodology can’t use constants for common strings. There are ways 
to massage the data to use constants, but that’s left as another exercise for the reader. 


94 


develop 25 


March }996 







Listing 2. GetA! I Re sources 

global GetAllResources(ResTypep NewtType) 
begin 

local result ; 

local atID 0; 

// See if we can read in resource ID 0. If so, increment the 

// next resource ID; if not, set the ID to 120. 

try 

AddArraySlot(result, GetResource(ResType, atID, NewtTypej); 
atID 1; 

onexception |evt.ex.msg| do 
atID := 128; 

// Start at the current resource ID (either 1 or 123) and 
// continue reading in resources until an exception occurs* 
loop 
begin 
try 

AddArraySlot(result, GetResource{ResType, atID, NewtType)); 
atID := atID t 1; 
onexception |evt*€x*msg| do 
break; 

end; 

result; 

end; 


Listing 3. Creal'elanguogesFrameFromRsrc 

global CreateLanguagesFrameFromRsrc{ResFilePath, LanguagesSymArray) 
begin 

// Throw if there aren't exactly 5 languages, 
if Length(LanguagesSymArray) <> 5 then 
Throw(* Ievt.ex.msgI, 

"The LanguagesSymArray must be exactly 5 elements long."); 

// The languages frame array that will be returned 
local langFrame x- {}; 
foreach sym in LanguagesSymArray do 
langFrame.{sym) :“ {}; 

// Could use a constant since currently must be exactly 5 languages, 
local numLanguages Length(LanguagesSymArray); 
local r := OpenResFileX(ResFilePath); 

local locResourceArray := GetAllResources("LOC#", 'binaryObject); 

/* Process the LOG# resources. The format of the resource is: 

16-bit count of number of string sets 
string set 1 
string set 2,.. 
string set n 

(continued on next page) 
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Listing 3. CreatelanguagesFromeFromRsrc (continued) 
string set: 

pathexpression as C string 
English as C string 
French as C string 
German as C string 
otherl as C string 
other2 as C string 

local numStringSets ; 
local pathExpr; 
local tempstring? 
local atIndex; 

foreach locResource in locResonrceArray do 
begin 

// Get the number of string sets. 
numStringSets := ExtractWord(locResource, 0); 

atindex ;= 2; 

// Grab each string set. 

for stringSet ;= 1 to numStringSets do 

begin 

// Grab the C string that is the path, 
pathExpr := ExtractCString(locResource, atindex); 

// Update index counter. 

atindex ;= atindex + StrLen(pathExpr) t 1; 

// Create path expression for following strings. 
pathExpr := call Conipile("*" £r pathExpr) with Or 

// Get the language strings and jam them. 

// WARNING: This code will ignore zero-length strings. 

// There are rare cases where you actually want an empty 
// string for a particular translation; in this case, you 
// could modify the code to throw an evt.ex.msg with the 
// appropriate error. 

foreach langSym in LanguagesSymArray do 
begin 

tempstring ;= ExtractCString(locResource, atindex); 
if StrLen(tempString) > 0 then 

langFrame.(langSym).(pathExpr) s = tempString; 
atindex atindex + Length(tempString) t 1; 
end; 
end; 
end; 

CloseResFileX(r); 
langFrame; 
end; 
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PUTTING IT ALL TOGETHER 

Once you’ve created the languages frame, you can use SetLocalizatioiiFrame and 
LocObj in your project to localize your strings. The sample on this issuers CD 
(Compile Time Strings) uses the code shown in Listing 4* This code is more general 
than you may need, in that it creates the frame from either text files or resources. The 
last line sets up a constant for the English (that is, the default) language frame. You 
can use the constant English strings as part of the first argument to LocObj. 

The tocObj mechpnism con be used with any object, not just strings. This article 
looks only at strings, though the texl-based method will work for most types of objects." 


Listing 4. Calling SetLocalizationFrame 

// Create the languages frames either by text or by resource* 
constant kFromText := nil; 

// Create the kLanguagesArray constant for the languages. 

// The text method requires only as many languages as there are 
// text files; the resource method requires a 5-element array. 
DefConst('kLanguagesArray, 
call func(isText) 
if isText then 

^[English, French, German]; 
else 

'[English, French, German, Otherl, 0ther2J 
with [kFromText)); 

if kFromText then 

DefConst!'kLangFrame, 

CreateLanguagesFrameFromText( 

HOME & "StringsCommon.f", kLanguagesArray)); 

else 

De fConst(■kLangFrame, 

CreateLanguagesFrameFromRsrc{ 

HOME £ "strings.rsrc", kLanguagesArray)); 

SetLocalizationFrame(kLangFrame); 

// Define a constant for the English language frame, 
constant kStrings kLangFrame*English; 


YouVe probably wondering why we don’t create a wrapper fruictian to generate the 
correct LocObj call. Unfortunately, LocObj is a special type of call in the Ne\vton 
Toolkit; it’s evaluated as soon as the compiler hits it and it must return a constant value. 

CHANGING STRINGS AT RUN TIME 

The LocObj mechanism is designed for compile-time customization of your 
application. In other words, the LocObj function exists only in the compile-time 
environment of the New^ton Toolkit; you can use it only in places that will be 
evaluated at compile time. In some circumstances you may want to change localized 
strings at mn time. One example w^ould be a language translator application wEere 
you want the interlace strings to be displayed in the current source language. 


COUNTRY STRINGING: LOCAUZEU STRINGS FOR THE NEWTON 


97 






develop 


The raw chtA for the mntime strings exists in the langnfiges frame. The frame can be 
included in your package so that you have access to all the localized strings. This will 
add a significant amount of space to youi’ package; at wxirst, it will take up two bytes 
per character in the unique strings, plus the storage occupied by the symbols and 
frame structure. 

You’ll need to add some nmnmc support for switching language elements of the 
interface. The main task is to decide what view'^s need to be updated when a language 
is switched. The simplest w'ay to do this h to recursively propagate a conditional 
message send through the application’s view' children: 

//In application base view ... 
myApp.PropagateLanguageChange := func{) 
begin 

// conditionally recur through all the kids, 
foreach child in :ChildViewFrames() do 

// "x,y exists’* only checks for y using proto inheritance, 
if child,PropagateLanguageChange exists then 
child:PropagateLanguageChange(); 

end; 

This code w^on’t send to all children. To do that you would remove the exists test and 
just send the message, which will always be found .since the top-level parent defines it. 
If you make this change, you should add some sort of conLlitional check lor a message 
that does the real work of u(>dating (like “if child.DoLangiiageC^hange exists dien 

An alternative is tt) keep crack of which view s need updates. How you do it depends 
on your applicarion^i structure. Ty]iically you would maintain an array of die declared 
views that need updating. If the views that need u pda ring are well known, you’re 
better off using the latter method. 

Each view that requires an update will need to perform three tasks: change the text 
based on the source language; usually change the view BouikIs based on the new^ text; 
and redraw or refresh based on the new viewlkuinds ami text. Since it’s very likely that 
the view'Botinds will change, most of the work can be done in the viewSetupFonnScript 
method of die view. Remember that redisplaying with a new^ viewTounds requires 
sending a SyneVHews w hich has the side effect of sending all view Setup messages. 

This means that you can use die SyncView call as your message to indicate that 
die source language has changed. WTien a view opens by normal means it will also 
use the correct source language. Note diat in some cases you may want to use 
RcdoChildrcn, w hich has die same basic effect as SyneV'^iew sent tt> all children. 

One caveat is that both SyncView and RedoC^hildrcn arc expensive calls. You should 
limit the places where the language can change. An example of runtime customization 
(Run Time Strings) is provided on the CD. 

READY TO ROCK AND ROLL 

With the code from this article, you can now' make all your applications world ready. 
If you’re just staning an application, take the rime and use LocObj where you should. 
If you already have a project, retrofit it. Then take the code samples, customize diem 
to your heart’s content, and code away Today English, tomorrow^ the world. 


Thojnks Jo our fechnical reviewers Bob Ebert, Mfke 
Engber, David Fedor, and Martin Gannholm. • 
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Newton 
Q&A: 
Ask the 
Llama 


Q 

A 


Ncrw that Newton 2J) is shipping, what has changed? 

A fair question, and one that’s been much on my mind* Newton 2,0 solves some 
of die problems previously presented in this column in much better ways. So 
I’ve gone back over old questions to see what has changed. Til start out this time 
by revisiting those questions that have new answers. (Quesdons that dealt with 
subsystems whose APIs on the Newton 2.0 OS are drastically different will not 
be covered; most of these have to do with routing, which has undergone a 
significant change for the better, while some have to do with communications,) 


Q 

A 


Haw do J cf'eate my awn class af hinajy a^ect? (Issue / 8) 

In the Newton Lx OS you had to use SetClass on a string object to make some 
odier binary object. In 2.0 you can just call the new" function MakeBinary. So 
the line of code to define the canonical CharlD object (see the original answer) 
changes to 


De fConst(‘kDe faultCharlDOBj, MakeBinary(4, 'CharlD)); 


Q 


/ would like to add a [button I view I Llama] to [Notes 1 Dates I Names I efc.]. How can 1 
do that safely? (Issue 19) 


A 


In the Newton 1 ,x OS there was no supported way to add items to the built-in 
applications. In 2,0 there are a few ways you can do this. 


For general changes, yotr can add new stationery to Notes, Dares, and Names. 
For example, you could add graph paper to Notes, You could also define new 
card styles or views of a person in Names, 


Names and Dates also let you add whole new classes of things. For instance, you 
could add a Pet type of names entry that would appear in the New pop-up 
menu along with Person, Company, and Group, 


The Dates application has an API to add new" types of meetings. It also lets you 
add items to its Info button. 


In addition, there’s a general API to register buttons that can show up in the 
“blessed” apphcation’s status bar. It’s up to each application to decide whether 
and how it will display registered buttons. You should no longer use the 
unsupported keyboardChicken hack. 

Note that on the Newton 2.0 platform there’s still no support for adding 
buttons to built-in slips. For example, if you wanted to add something to the 
alarm picker for a meeting, you would need to add a new type of stationery 
that’s a superset of the alarm picker. 


Q 


Fve wfitten my own IsASCUAlpha^ IsASCllNumeric, etc. fimctions. They seem to be 
really slow. Why is that? Here's tny IsASClIAlpha: [code not repeated here; all the 
fiinctions work on stiin^] (Issue 20) 


The llomo is the unofficial moscot of the questions to Newton Mall or eWorld DR LLAMA or 

Developer Technical Support group in Apple's to AppleLink DRXLAMA. The first time we use o 

Newton Systems Group, Send your Newtorvreloted question from you, well send you a T-shirt,* 
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Most of the comments from the original answer still hold. However, in the 
Newton 2.0 OS the string could be a rich string; that is, there could be an ink 
character inside the string. That means the compare functions have to check 
whether a particular character was klnkChar. 


Q 


When / tty to add an index tQ my soup I sometmies get an exception -48019^ but not 
always. Whafs going on? (hstte 22) 


In early versions of Newton, if you added an index on a slot, and an entry in that 
soup had a value of nil for that slot, you would get an error. As of the Newton 
2.0 OS this is no longer a problem. You can add an index even if there are 
entries with nil values for the slot in the soup. 


Q 


/ have an applicatmi that uses ADSP to cmmect to a server on the desktop. I want the 
server to handle nmltiple Newton devices contiecfed simidtaneously. Unfortunately^ if a 
connection fails after ifs opened^ the server docsn-'t seem to he able to identify it as a new 
cotinectkn when the Ntwton device reconnects. This causes prohlmts in the setter's 
ability to handle multiple connections. Can yon help? (Issue 23) 


A 


In the Newton 2.0 OS this no longer occurs. The Newton device will generate 
a new ID for the connection. 


Q 


Since thetr are changes between Newton Lx and 2.0, what feattires in 2.0 can ! rely 
on? IVbat is the core set that defines Newton 2.0? 


At this time there is no piublished core set of Newton Script-level features that 
you can rely on. VV%Ve confident that you can rely on the features of the 
NewtonScript language and major components like the view system and 
communication endpoint interface. However, yf>u can't count on individual 
protos or even the internal applications being there. Since we license Newton 
technology to other companies, they could proiliice a Newton device that 
doesn’t include Names, Dates, or other built-in features. They may also 
produce Newton devices that have features that aren’t present in Apple 
products. 


The key is to test the features you rely on. If you find that some of the features 
you need are missing, you can either run in a less-featured mode or just not 
open your application. As a simple example, suppose your appHcation runs only 
in a limited set of screen sizes and aspect ratios. You can give your base 
application view a viewSetupFormScript that looks something like this: 


myBaseView.viewSetupFormScript := fone() 
begin 

local screenSize :^ GetAppParams(); 
local aspectRatio := screenSize.appAreaWidth / 
screenSize.appAreaHeight; 


// very simplistic test, no MINIMUM evenJ 
if aspectRatio > 1.0 then // landscape 
begin 

local maxHeight kMaxAppWidth? 
local maxWidth kMaxAppHeight? 

end? 
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else begin // portrait or square 

local max Height j- ]cHaxAppHeight; 
local maxWidth := kMaxAppWidth; 
end; 

if screensize-appAreaWidth <= maxWidth AND 
screenSize.appAreaHeight <= maxHeight then 
begin 

self.viewBounds := RelBounds(_); 

If other setup stuff 


end 

else begin 

// cannot operate at screen sixe 
:Notify[kNotifyAlert, EnsureInternal(kAppName), 
EnBurelnternal(kErrorWrongScreenSize)); 

AddDeferredSend{self, 'Close, nil); 
end; 
end; 

For global fiinctions and variables, you can use the GlobalFnExtsts and 
GlobalVarExists utility functions. To find out whether a builtTu application 
exists, you can check the root view with the appropriate synibob 

// check for Dates 
if GetRootO .calendar then 

// check for Names 
if GetRootJ)-cardfile then 

// check for Extras 
if GetRoot().extrasDrawer then 


For protos, you can try to access the proto and catch a frame reference 
exception. If the exception occurs, the proto is not pre.sent. 

In general, it’s a wise idea to do all youi* existence testing as your application is 
launching. Set flags in your base application so that you test for existing features 
only once. 


Q 

A 


h thtrs a hard'mar^-timqm ID that I can access on a Newtown device^ 

At tills time there’s no bmlt-m hardware-unique ID, nor is there an API for 
accessing one if it existed. However, this doesn’t rule out having such an API in 
future Newton devices. 


Q 


/V// using a Newton 2.0 protoSoupOvefT^iew and I want to change the font style. Htm 
do I do that? 


A 


This is one of those things that are obvious once you make the connection. You 
use the Abstract method of protoSoupOverview (and protoOverview, for that 
matter) to build die shape that’s displayed for a particular soup entry. Notice 
that you’re returning a shape, with ail that entails. The chapter on drawing in 
the Newton Progratnmer^s Guide says you can include a styles entry in a shape 
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array, allowing yon to specify things like font style. See the DTS Sample Code 
Checkbook on the Newton Developer CD for an example. 


Q 


/ mtmd that some of the huilt-m applkatiom have keyboards in their slips —for 
example^ the new name editor in the Na?nes file. Is this stationery based? Is there a 
magic slot I can set? Is there a proto? 


Those keyboards are just views based on protoKeypad that are laid out as a 
child view of the slip. Ail you need to do is lay out your own protoKeypad and 
set up the definitions appropriately. There is no supported magic slot* 


Q 


r?n tTjing to use a protohistFkker to display a soup structure that has nested frame 
entries. I can V get the UstPkker to work. Am 1 doing so?nething wrong? 


A No. The default listPicker proto doesn’t work with items that are accessed via 
path expressions. However, if you make the following three changes, your 
listPicker should work fine. 


First, you have to specialize the GerObjSlot inethod {)fyoiu- pickerDefi 

GetObjSloti func(iteffli fieldPath) 
begin 

if ClassOf(fieldPath) <> 'pathExpr then 

//if not a path expression^ return the inherited value 
return inheritedsGetObjSlot{item^ fieldPath); 


// otherwise, if there is no item, return nil 
if not item then 
return nil; 


// there is an itevnr so get the real value, since the item 
if could be a NameRef or an Entry 
if IsNameRef(item) then 

local val := EntryFromObj(item); 
else 

val t- item; 

// assuming we have a real thing, access the real data via the 
if path expression in fieldPath 
if val then 

val*(fieldPath); 

end 

Second, if you specify a validation frame in for your listPicker, the nesting of 
that frame must match the nesting of your soup entry. 

Finally, modify your pickerDef so that the column that displays the data based 
on the index path uses the appropriate index path. 


Thonks fo our Newton Partners br the questions 
used in this column, and to jXopher Bell, Henry 
Cote, Bob Ebert, David Fedor, Jim Schram, 
Maurice Sharp, and Bruce Thompson for the 
answers." 


If you need more answers, check out 
http://dev.info*apple.com/newtort on the World 
Wide Web or look at Newton Developer Info on 
AppleLink." 
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THE VETERAN 
NEOPHYTE 

Killing Time Killers 


B03B JOHNSON 


So Viu sitting at my desk, mouse in hand, digging 
diroiigh the guts of my Mac, cnang to track down yet 
anodier pathetic bug. The only trouble is, this is 
getting dull. I Ve done it a thousand times, and 1 always 
win; ids just a question of how much time the old ball 
and chain is going to eat up this time. Worse, the wind 
is blowing 20 knots right outside tiiy window, and for 
the windsurfers in tlie crowd, y(>u know the ejiquisite 
ttjrture of good w ind chat yoLi aren’t allowed to 
transfunn into mind-blowing speed. 

Maybe for you it’s that you’d like to get home to see 
your insanely great mate. Or you’ve got kids wiiose 
naines you can’t pronounec. Ids even likely that some of 
you just graduated from college and arc still astonished 
that they pay you for something that’s so much fun. But 
yon’re thinking, ^'If I can get this hug fixed quickly, 1 
can get hack to writijig that nid Marathon hack to make 
the odier net players slower than me.” Perhaps your 
boss has started to notice chat you spend a lot of time 
on the job but you don’t really get very much done. 
Getting a little nervous? What if he’s thinking of pulling 
the plug on your baby because you’re too slow? 

Or maybe you shipped the 1.0 version, but it had a few 
coo many bugs, and was so incensed that 

they broke with the tradition of objective journalism 
and are calling for your head. People w ho bought your 
software widi actual money have been calling every day, 
filling your answering machine %vith unveiled threats. It 
seems that you left: a bug in there that just cost several 
thousand people each about two weeks of valuable time, 
reentering their data. 


In particular, recogni/.e that the w^asted time frojii 
programming errors and hugs gets exponentially more 
expensive the further into the process you get. I f I make 
a syntax error, 1 just fix ii and recompile. If 1 toss buggy 
code over the fence to the testers, now I’m w^asting 
then* time. If [ ship software w'ith occasional crashing 
bugs that I just can’t quite track dowm, I’m wasting 
thousands of people’s time. 

The point is, there are lots of ways to w'aste time while 
programming. Fni here today to offer some ideas (Hi 
how to save time through better programming habits, 
so that you can cake up windsurfing, or maybe the 
electric guitar, or learn hciw to pronounce your kids’ 
names, or gain “the powder to crush die other kids” 
w' h i le p 1 a yi n g M a ra th tj n. VVh e 11 ever I m e n c i o ii 
windsurfing, substitute your favorite i|uaIit}^-ofilifc 
enhancer. 

ril use some real life exam[>les, and wee’ll see w hat sorts 
of lessons we can learn from diem. IVe categorized 
these ideas in three ways. First, there are some obvious 
time wasters that can be eradicated; these aren’t really 
bug related, just daily lime wasters. Considering how 
much time bugs cost, the second category consists 
of high-value rules that can find bugs quickly and 
painlessly. Finally, there are die super-value niles that 
prevent hugs from happening at all. Be sure to consider 
how these ideas might apply in your specific 
circumstances. 

RIGOROUS^ YET REUSABLE 

OK, Fin in the midst of wTiting the MMU tables for 
Blat, and I realize that I’ve already got a similar table. 
Not being a fool, I know^ not to rewrite code I’ve 
already written, so I open that file and casually copy 
and paste the table into my current work. Oh no, not 
another copy and paste casualty! Apparently I missed 
changing those two table entries, and with MMU tables 
diat means the machine hangs before MacsBug loads. 
Seems like every time 1 paste in code there’s something 
1 miss, making it not compile — or worse, causing a 
malfimction. 

Even with small chunks of code. I’ve found it helps to 
review^ the pasted code line by line, carefully, and not 
to assume that since it ran before, it’ll run now. Some 
subtle assumptions may have changed, and even though 


B03B J0HW50N tbQ3b@rahu!.net] is completely whacked out 
about windsurfing, and fakes summers off in order to windsurf 
every day. But since it's winter, he's doing consulting so that he can 
poy for his next windsurf board and windsurf trip to Aruba. Bo3b 
prefers to be addressed as "Bob/ since the 3 is silent.* 


Where'5 Dave? Thai other Johnson, who usually writes this 
column^ is probobly at the public library researching his obsession 
du [our, loking his dogs For very long walks, or reclining on the 
couch reading o book. Since he's cut back hts working hours, 
weTe having guest Neophytes write this column. We can't promise 
they'll all be Johnsons, however.* 
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reusing code is certainly superior to writing it again, 
don’t be misted into thinking this is risk free. A more 
powerful technique is to seriously modularize code, so 
that when I copy and paste T take an entire routine, not 
just a few lines. With a well-defined interface, the 
chances of blowing it are gready reduced. This means 
adopting the habit of writing each routine with the idea 
that Pm going to reuse it laten This radically improves 
every routine I write. 

New rule: Reuse code modules, not code fragments. If 
the code has to be altered, inspect it as if it were new 
(which it is). 

VERBOSE, YET LUCID 

While in the guts of Font/DA Mover, 1 ran across some 
very strange code diat didn’t make any sense to me at 
all — and it wasn’t documented. It was never executed 
as far as I could detennine, but I painstakingly figured 
out that it was looking for System file 3.2 and, if found, 
would ()atch the OS to fix a font bug. I would have 
saved a full day of effort had there been a comment in 
that funny little splat of code. Like I’m supposed to 
know^ what die bugs in System 3.2 are off the top of my 
head? 

Comments really are necessary to make code reusable 
and maintainable. 1 always write “strategy” comments, 
which say what the routine is trying lo do, and avoid 
writing “tactical” comments, like whai iPs doing line by 
line. Remember, sometimes the time savings occur in 
the future, not at die moment. I’ve found that skipping 
comments is being penny wise and pound foolish. 
Usually tlie strategy^ comments help clarify my thinking 
on the routine as w^ell, so there actuallv is a short-tenn 
gain. 

New rule: Always write strategy comments. It’s possible 
to decipher intent from the code, but why not just 
explicitly say it? 

PLUMP, YET HONED 

] used to think it w'as important to save every line of 
assembly code that was possible. The first program 
I wrote for the Mac was iAnaclock, an analog clock 
prfjgram, and 1 remember thinking tliat if I changed 
the order of some routines I could save code. Don’t we 
all get into that mode somctiines? If I just change these 
two lines, I can save an assignment, and blah blah. It 
must come from tlie old 128K Macs and Apple IIs. 

Well, guess what? These machines are so stuffed full of 
junk nowadays that saving just oiie or tw^o lines is as 
meaningless an effort as trying to decide liow^ many 
demons fit on the head of a transistor. Worse, 1 spent 


rny own valuable time deciding sometliing that has zero 
impact. Sorry, no can do anymore. My philosophy now 
is: write it straightforward, easy to read, vanilla. I w^ant 
to save my windsui*fing time, not pretend that 1 know 
up front what needs optimizing. In the Anaclock 
example, the computer had an entire second between 
screen updates. MTen 1 actually measured execution 
time, all the time was spent in CopyBits updating the 
screen, and waiting in the main event loop for die next 
second to arrive. There was zero measurable time in 
my entire clock calculation and offscreen drawing code. 

New rule: No premature optimization. Measure with 
performance tools first. Then optimize only where it 
counts. 

TEMPERAMENTAL, YET DISCRIMINATING 

During System 7 development, we once tracked down 
a bug, taking seven hours in the middle of the night to 
find it, and it wound up being a bad parameter passed 
to a ROM routine. Incredibly, I could have found that 
bug in about 15 seconds if I’d used the Discipline tool. 
Nowadays, I never debug something by hand unless it 
has passed all the dcliugging tools that Fred Huxliam 
and I talked aliout in our article in develop Issue 8. 

There are lots and lots of tools available now, and I use 
all of them. 1 don’t care how hard diey are to use; if 
they can find a bug in seconds that might take me 
hours or days, then I win. 'This includes such notorious 
tools as Blat and Jasik’s debugger. I know Blat’s a pain, 
since it doesn’t work on all niacliines, but hey, it’s too 
valuable to skip. Same with Jasik’s debugger. Sure it’s 
confusing, but it’s got features no one else provides. 
Before throwing tlic stjfr^'Lure over to the testers, I 
make sure it passes all the tools. 

High-value rule: Use the best tools, all the time. Don’t 
.spend time in a debugger when a test tool will hand 
you the answer on a silver platter. 

SPECULATIVE, YET REWARDING 

As part of a contract, my job was to make a program 
to save, print, and display 300 dpi bitmaps that were 
scanned in from a fax machine through new hardware. 
Tills was to be a low-cost scanner, and rny software 
would be die initial scan-and-display code. Nothing 
too fancy, but it stiU required basic functionality. I bid 
15 hours for the entire program. Was I crazy? M^ell, of 
course, hut not for this reason. I used MacApp to give 
me the application functionality, and the FracApp300 
sample program was a good starting perint for 300 dpi 
bitmap handling. All I really did was add an object to 
talk to the scanning hardware, and I came in under 
bid! 
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Sometimes learning those new tough coding tools can 
really pay off I generally try to sample eveiy^ new tool 
and coding advance that comes along to see if it can 
help me save time. MacApp was clearly a massive win, 
because it focused my programming onto teensy parts 
to he added instead of all the Toolbox calls of a typical 
application. In addition, it was fully debugged and very 
robust, giving me a more solid final application. I try 
nf>t to be wedded to any given style or approach; I just 
want to use the best stuff currently available. 

High-value rule: Try new things. New ideas, approaches, 
tools, and programming styles can be like winning the 
free-time lottery. 

PAVLOVIAN, YET TRAINABLE 

Sometimes it takes a while to recognize bad habits for 
what they are. While writing Bowser, which turned 
into Mouser and then MacBrowser, 1 wrote the source 
code parser by hand, to look for keywords. This was 
not a good strategy. It was quick and dirty, and stayed 
dirty, and w^as less quick all the time. It would be 
reasonable to expect that after modifying the parser 
for the eighth or ninth time to handle some stupid 
language exception, I would have gotten a clue tliat tliis 
w^as not the right approach. The right answer was to 
learn how the lex and yacc tools worked, since parsers 
for both Object Pascal and C++ already existed in that 
fonnat, 

j\fter seeing similar bugs go by several times, it 
becomes clear that something must be done to stop 
that kind of bug, I don^t want to spend time fixing the 
same problem over and over again, so now my goal is 
to permanently fix bugs so that they can’t happen again. 
By this I mean changing how 1 do things, so that that 
specific bug will either be caught quickly or never 
happen again. It can be as simple as adding a test to a 
test suite to ensure that bugs cif that form are caught 
immediately, or adding an assert to catch that error. Or 
it can be as hard as changing my programming habits 
to never use pointer math. WTatever it takes, T try to 
learn firom each hug and make sure it can’t happen 
again. Especially after IVe done something twice, it’s 
time to write a tool to fix that problem. 

High-value rule: Leam from mistakes. If my dog gets 
honked on tlie nose every time he gets near the door, 
he ieams to avoid the dofir. I w^anc to be at least as 
smart as my dog, 

FASTIDIOUS^ YET NOBLE 

Another slant on the Bowser problem is that I w^asn’t 
really trying to make the parser right. If Pd been a little 
more quality conscious, I wouldn’t have gone that 


route, because it was clear that the hand-built parser 
was clunky. 

s\s noted before, the longer a bug survives, the more 
expensive it will be. Early bug extinction is my goal, so 
1 consciously try to write with quality in tnind. Examples 
are: using the strictest coding rules, not using any 
tricky features of the compiler, using ty|>e-suggestive 
variable names, insisting on type ehccking, not using 
raw pointer variables, avoiding type coercion, adopting 
a simple easy-to-read style, vmting clear module 
interlaces, and using full w^amings in the compiler 

Since I started noticing how much time bugs cost, IVe 
changed my mindset on tliem. I no longer automatically 
accept that code will just have bugs. I hate Vm. I want 
to kill Vm, Better, I want to kill ’em before they hatch. 
Since tliey take up my personal time, T feel it’s only 
proper to take it personally when they show up. 

Super-value rule: Write with quality in mind. As they 
say, the inner game of programming is so important. 

UGLY, YET EVOLVED 

Once upon a time, I was asked to fix a couple of bugs 
in Font/D A Mover and make it work mth TrueType 
fonts, as an interim solution before System 7. The 
program was so disgusting to me that I just had to go 
in and clean it up. Move this here, change these names, 
document some pieces, take out the redundant code, 
modularize some pieces — ah, how aesthetically 
pleasing. Oops ... I just introduced a couple of bugs 
while I was “improving” the code. Tt felt Uke progress, 
but actually it was just motion. You know, like company 
reorgs. 

What to do? Don’t “improve” code, unless it’s never 
been debugged. Any fully debugged code, no matter 
how shoddily written, is superior to newdy written 
code, no matter how^ pristine. It went against my 
grain, but the right answer was to leave it gross. That 
heavily used Font/D A Mover code had thousands of 
hours of value in it, with literally millions of testers, 
that were all lost when T rewrote it. Rewriting it took 
rime that I w^anted to spend on something more 
valuable, Uke fixing the last few remaining bugs — 
and then getting outside and windsurfing! Once I 
rewrote the code, it was like a new^ program, and thus 
needed a full developmenc/testing/dehugging cycle. 

I backed off to an earlier “skanky” version and just 
debugged that. 

Super-value rule: Never rewrite sometlimg that’s 
been fully tested. It may be ugly, but evolution is on 
its side. 
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BORING, YET ELEGANT 

We nil know about the “cool” things that C can do, and 
some tricky ways of using it, but sometimes isn’t it a bit 
like juggling live weasels? When I found that using a 
#define had added an extra unwanted character to each 
place I used it, it no longer seemed so clever, and felt 
more like I was playing tricks on myself Or how about 
that favorite of putting an actual assignment in an if 
statement? It’s cleverly camouflaged, but there aren’t 
any natural predators here, so Fm not sure this is needed. 
These simple examples obviously don’t do justice to the 
possible tricks that weVe all seen, but they all cost time 
and rarely add value, 

OK, so it’s clear that being “clever" often winds up 
being a way to play tricks on myself Is diere anything 
wrong watb doing it shiiply, in a straightforward, vanilla 
style? 1 kiiow^ for sure I’ll get it done sooner and, even 
better, the programmer who has to maintain this code 
won’t have to waste a bunch of time Linderstaiiding 
mindless tricks (remembering of course that that 
maintenance programmer might very^ well !)e me, two 
years alter 1 fcjrgot what tricks 1 was jilajdng). Anti let’s 
just forget the malarkey about it saving code. Is it really 
worth saving 10 w hole hyl^es out of a 16 meg machine, 
at the expense of wasting my time? I want to count 
cycles and bytes only in places where it makes a 
measurable difference. 

Super-value rule: Write vanilla code. Doing it sim]>ly, 
;viul the same w^ay each time, also makes it more likely 
to be correct. 

ASSERTIVE, YET FRIENDLY 

Back in the tleep tlark Macintosh past, 1 w'rote the 
tiriver ft>r an external RAM disk called DASOH. 

This high-speed serial link retjuired some different 
tlebugging tactics than I’d used previously, I>ecause I 
coiikin’t step through ihe code; it was time critical. 

Any slight perturbation in .speed would overrun and 
cause an error, hut I still needed to debug it. It was like 
a “look Morn, no hands" t)^ie of debugging. Clode 
in.spection is OK, l>iit 1 \vanted to he sure it w'orked as 
I read it. Have you ever read a piece of ciide that took 
a branch you didn’t expect? 

The answer, although 1 ilidn’t use the name at the time, 
was t(j use asserts."These have Iieen talked about a fair 
amoimt, and youVe probably used primitive asserts 
under the name of DehugStr. Nowadays, the most 
powxu ful combination Tve used is to hook together 


asserts with a failure handler like MacApp’s catch/fail 
mechanism. Asserts make it easy to build a debug-only 
version that checks every stupid thing that can go 
wrong and lets me know right tip front during testing, 
but doesn’t compile into the final version. The 
catch/fail saiff makes it easy to handle every possible 
error in a graceful way. (See the article “Using C++ 
Exceptions in C” in diis issue.) 

If something absolutely positively cannot fail, I use a 
debugging-version assert to catch the occasional times 
wften it does fail, so that I can surprise myself early and 
not spend hours tracking down the “impossible” error. 
One great thing to check with asserts is input parameters, 
to catch those inevitable times w^hen some routine 
passes in rubbish. 

Super-value rule: Use asserts along with a failure handler. 
Catching bugs as they happen is vastly superior to 
backtracking 15 miles after the program crashes. 

ENDING, YET BEGINNING 

Fm not going to [ireiend tluu this is all there is to the 
idea of skiving time, hut hopefully the idea seems worth 
pursuing. It has certainly helped me get better at my 
canang jibes and, not incidentally, better at programming 
at the same time. 1 ligheiMjiiality code, fewer bugs, 
earlier ship dates, happier customers, and more free 
time. Yiip, I’d say it’s been wortli it. 

If you’ve got some iulditional tinie-saving ideas, Fd 
naturally l>c interested in trying them tfK>, so write me 
at bo3b@rahul.net. 


RECOMMENDED READING 

• Wrrf/ng Solid Code by Steve Maguire (Microsoft 
Press, 1993). 

• Debugging the Development Process by Steve 
Maguire (Microsoft Press, 1995). 

• "'Macintosh Debugging: A Weird Journey Into the 
Belly of the Beost" by Bo3b Johnson and Fred 
Huxham^ develop Issue 8^ ond "'Macintosh 
Debugging: The Belly of the Beast Revisited" by 
Fred Huxham and Greg Morriott, develop Issue 1 3. 

• Zen and the Art of Windsurfing by Frank Fox 
(Amberco Press, 1988). 


Thanks to Jeff Barbose, Jim Friedlonder^ Brian Homlin, Fred 
Huxham, Dave Johnson, Jim Reekes, and Polty Wo Iters for iheir 
terribly helpful review commenis. * 
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Macintosh 

Q&A 


Q 


Pm having problems with otir caching drivmi on the Power Macmtosh 9 WO. Our 
drivers allocate a large amount of Rj 4.M (up to 4 MB) early in the boot process. If I set 
the driver^s cache size to 4 MB^ the computer locks up as sootr as the dtive?^ is exeaited. 
If! set the cache size to 2 MB, the driver loads and executes properly, but the compitter 
gets a bus efivr much later^ in the boot process (after MacsBug loads and after the Mac 
OS screen is displayedy but before the Finder exeattes). If I set the cache size to 1 MB, 
evetytbing rum properly. Whafs going on here? 


Because of Open Firmware requirements^ the boot stack on the new Power 
Macintosh 9500 CPUs was changed to 4 MB* As a result, you can^t grow die 
system heap past 4 MB or a system crash will occur* If possible, try to defer 
allocating memory until EMIT time* The 'sysz' mechanism is supported by the 
enabler ('boot' 3) when INITs are being loaded* 


Q 


We want to maximize our throughput aavss the PCI bus between Macintosh memofj 
and a block of static RAM on our card. This static RAM is also accessible ft oni an o?i- 
card DSFy which constantly reads/tnodifies RAM. The DSP isn't directly on the PCI 
bus, so it can't easily partkipate in cache coherency schmies. Whafs the best way to get 
data across the PCI bm to andfi^om this meimny? 


1 he PowerPC processor can only burst to anti fnmi a cacheabk memory space. 
Your best option is to use BIockMoveDataUncached. This doesn’t use burst 
transfers, but rather uses floating-point loads and stores. You may want to 
design your own algorithms, using the double declaration in C to get compilers 
to translate BlockMoveDataUncached into flt>ating-point loads and stores. 

E'or more iubjiniation, see Chaj^ter 9 of Designing PC! Cards and Drivers for 
Powei^ Macintosh CotuptUeis, and lechnote 1008, “Understanding VCA Bus 
Performance.’’ 


The Power Macmtosh 9^00 Devtdoper Note says that the sound-in poyr for the 9500 
has 4-conductor reffitirements. WFat is the 4-i ondumr pinout? Does the PlmnTalk 
miavphone work on the 9500? 


The 9500 has stereo in (supporting left, right, power, and ground) and requires 
a mini stereo pi ug that you can buy today — no wacky new pinouts* The 
PlainTalk microphone works fine on the 9500* 


Q 


Is there any information on writing native SCSI disk drivers for the PCI-based Power 
Macintosh co/nputers? h? pankular, whafs the propei^ way to mstall a native driver on 
a SCSI disk: is thm' a ^pecial panition type for a native driver, or should there be a 
standard SCSI disk driver that loads a PmverPC code fi^agntent? 


Apple doesn’t support native SCSI drivers yet (this will be a feature of Copland, 
die next generadon of the Mac OS). You cmi write a native SCSI Interface 
Module (SLM). Remember that a driver is the software that handles a particular 
SCSI device, while a SLM is responsible for SCSI controllers (for example, PCI 
or NuBus^” cards). 


Normally, SCSI 4 J drivers are loaded off the Apple_Driver43 partition, and 
SLMs are typically loaded from the disk contrciller firmware (PCI card). If you 
want to load a native SIM off of the disk, you’ll have to encapsulate the code 
fragments and read and link them in from your standard 680x0 driver. 
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Q 


m SCSI rai/tmes rhif 6^K data if/ot^ks (m get the highest transfef 

rates possible with the tape diive we'^re iisin^. On the Fmem^ Macintosh (SI 00/SO 
or SI 00/100)^ if the mouse is moved dminga 64Ktiansftr^ the rnrsm- isjmnpy. 
Lowaing the cache size to J6K reduces the p?-oblem to an acceptable level bur kills the 
transfir ra tes. IVe^re using SCSI Manager 4.3. How do we avoid the jumpy amor 
while mamtainwg maximum throughput? 


Your jumpy cursor is an indication that you aren’t properiy impiementing SCSI 
direct memory access (DMA). When using the 8100 (and PCI-based machines) 
for DMA transfer efficiency, you should ensure the following: 

• Your data is aligned on 8-byte block boundaries. Since the DMA hardware 
can’t do odd transfers, it must perfonn programmed I/O to handle at least 
part of the transfer if the data isn’t aligned. 

• Your physical memory buffer is contiguous (which you ensure by calling 
LockMemoryConriguous). Otherwise, the DMA transfer will have to be 
broken up; this will especially be a problem if virtual memory is turned on. 


Also, if you have disconnects enabled in your device or driver, it’s possible that 
the transfer is getting broken up and some VBL activity is occurring. The 
bottom line is that you don’t want a SCSI disconnect to occur during your 
transfer. 


Q 

A 


Is it possible to create and resolve aliases a.^chronomly? 

No, you can’t resolve aliases asynclironously because the Alias Manager uses all 
synchronous File Manager and Device Manager requests. 


Q 


Is there a QuickTime codec for converting QuickDrim GX pictures to QuickDraw 
PICTformat? If so., canyon provide this? 


At a session during Apple’s 1995 Worldwide Developers Conference, a new 
technique for exporting (QuickDraw GX pictures as QuickDraw PICT files was 
demonstrated. The method makes use of QuickTime and a new codec that’s 
included in the QuickDraw GX extension version LI and later. With this codec, 
you can embed a flattened QuickDraw GX picture into a PICT file (or a 
QuickTime movie). We recommend that you use this method if you want to 
allow your QuickDraw GX application to exchange pictures with existing 
QuickDraw applications. You can find sample code demonstrating the use of 
this codec in the Macintosh Technical Q&A “Embedding a GX Picture into a 
PICT” (GX 07). 


One important feature of this codec is that it does not convert QuickDraw GX 
pictures to QuickDraw' PKTTs in the traditional sense of the word “convert.” 
What it allows is the embedding of QuickDraw GX objects inside a PICT file. 
The advantage of this is that it allows QuickDraw GX pictures to be viewed (but 
not edited) in any application that can open a PICT file. Although “embedding” 
is very useful, it’s quite different from “conversion.” 

Strictly speaking, it’s not possible to convert QuickDraw GX picmres to 
QuickDraw PKTs without loss of information, because QuickDraw GX has 
much greater frmctianality than traditional QuickDraw'. You can, of course, 
draw the QuickDraw GX picture offscreen and capture the result in a QuickDraw 
PICT, but you’ll lose much of the informaaon. There’s no way to represent 
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complex transfer modes, perspective, advanced typography, and so on under the 
QuickDraw imaging model. By using the new codec, you don’t lose any of the 
QuickDraw GX features. 

Note that tliis technique is quite different from that used in the older 
PicturesAndPICTLibraryx, which embeds a QuickDraw GX shape into a 
PICT by using picture comments. We recommend that you use the codec 
instead because picture comments have several weaknesses, including these: 

• They’re limited to 32K. 

• Many applications strip out any picture comments they don’t recognize. 

• DrawPicmre ignores all picture comments. 

Using the codec to embed the QuickDraw GX picture avoids these problems. 


Q How can Ifmd out which printer is selected in the Chooser? 

A Under the old printing architecture, you can locate the driver for the currently 
selected printer by accessing the 'STR ' -8192 or 'alis' -8192 resource in the 
System file. The 'STR ' -8192 resource contains the name of the current driver 
and the 'alis' resource contains an alias record that will take you right to the 
driver. Note that with older system software the 'alis' resource doesn’t appear in 
the System file. If the 'alis^ resource is present, resolve it; if not, locjk in the 
Extensions folder and in the System Folder for a file with the same name as 
'STR ^-8192. 


With QuickDraw GX installed, the ’STR ' -8192 resource still exists for 
backward compatibiUty with applications that don’t use QuickDraw GX 
printing. In this case the STR ' -8192 resource gives the name of the default 
desktop printer file. For applications that are QuickDraw GX sa^wy, the concept 
of a default printer isn’t important because the user can pick any printer from 
the QuickDraw GX Print dialog. 

Once you’ve located the 'ST^'R ' -8192 resource and you have die name of the 
cmrrent printer, you can then determine the printer’s zone and type using the 
’PAPA’ -8192 resource in the driver {if the traditional prinring architecture is 
in use) or by accessing the printer’s 'comm' resource (if the QuickDraw GX 
printing architecture is in use). Sample code demonstrating this can be found in 
the Macintosh technical Q&A 'Tocating the Selected Printer” (GXPD 36), 


Q 


When 1 call FOecoinpressImage during printing, it appears that the aist07n StdPisc 
bottleneck of the LaserWriter H.3 driver mPt called^ not? 


FDecompressImage doesn’t call through the StdPix bottleneck. The workaround 
is to directly call the StdPix bottleneck in the current grapliics port (or the 
StdPix obtained from calling SetStdCProcs if there are no custom bottlenecks 
in the current graphics port). For more informarion, see **PrinEmg Images 
Faster With Data Compression” in deiwlop Issue 24, 


Q 


When I attempt To open, the Iriiilt-in Ethernet driver with the OpenDrhm- call on a 
PCI-based Macintosh, the call fails, Whafs the cofrect way to access the bmlt-in driver 
on these new Macintosh computers? 
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The new PCI-based Power Macintosh computers use Open Transport for 
network services. This architecture is a precursor to the changes expected for 
Copland. Since Open Transport is PowerPOnadvc, there’s no longer a 
dependence on the 6S0x0-based Device Manager and Slot Manager. To 
maintain compatibility for the built-in Ethernet driver, an ENET shim was 
impiemented so that applications that called the Ethernet driver directly could 
continue to work. (Note that the ElNF/r shim is missing from the original 
Powder Macintosh 9500 release, but became available with latersofm^are updates.) 

The ENET shim o[)ens when OpenSlnr is called to open die Ediernet driver in 
NuBus slot 0. The shim intercepts this request anti loads a .ENET driver Gentry 
into the driver table. Subsequently, applications that call Open Driver will get 
the driver reference number for the shim driver, which then handles the various 
Control calls it receives. 'Phe shim works only for the huilr-in Ethernet device, 
not fur an installed PCI Ethernet card. 

For some code demonstrating how to do this, see the Macintosh lechnical 
Q&A “Ethernet Error on a PowerMac’' (NW 14), 


Q 

A 


How can I check whether the Open Tramport IP pfutocoi .wack /j haded? 

Open Transport provides the option to delay the complete loading ol tfae 
protocol stack, 'This reduces the use of system memory for the IP protocol stack 
until a TCP/IP applicatifxn is launched. To check w^hether the stack is loaded, 
call 04'InetGetInterfaceInfo. Tf it renims an [P address, the stack is loaded. If 
the returned address is 0 or the call fails, the stack is not yet loaded. Note that 
the call CO OTlnetGet Interface Info doesn’t force the load of the TP stack. 


Q 

A 


When we call DirFmdRecordGet, lee get the message kOCFJfwalidConrmand (-1 >01). 
Is there amthe?- way to get all reconh fivm a given catalog? 

The catalog about which you’re attempting to get record infbnnarion doesn’t 
support the DirFind Record Get function (few^ our there actually do). To check 
whether a particular catalog supports this function, you need to first call 
DirGetDirectoryinfo and check the features flags that are returned. Check the 
kSnpportsFindRecortlBit (see Inside Alacintosh: AOCE Application Intelfaces^ page 
8-31) to see if this call is supported. If it’s not supported, you’ll have to use 
DirEnumerateGet instead to get all the records from a catalog. 


You might w^ant to look at the DTS Catalog Peek sample code on the Mac OS 
Software Developer’s Kit, which uses the DirEnumerateGet call. 


Q 


Sometimes, after I copy an HFS volume one-to-one to a CD-ROM, aliases that look 
perfectly fine on the source volume are disconnected on the CD-ROA4 — the Alias 
Manager claims that it canH find the volume. Wlmt should I do to detect and fix a 
possible disconnected alias before writing it to CD-ROM? 


A 


Sometimes, wFen aliases move from hard drives to CD-ROAls, volume 
information changes, rendering the alias unresolvable. The Alias Manager 
requires the following pieces of information in order to identify a volume: 


• the volume’s name 


* the volume’s creation date (wFich should be a unique number) 
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• the volume’s kind (eiectable^ nonejectable, floppy disk, or foreign file system) 

The Alias Manager expects all three pieces of information to match. If they 
don’t all match, the Alias Manager attempts to identify the volume by matching 
two of the three items, trying for a volume match in this order: 

• by name and creation date 

• by creation date and volume kind (if the volume name changed) 

• by name and volume kind (if the creation date is not stable, as with some 
network file systems) 

Mflien pressing a CD-ROM, you’re moving aliases from a hard drive (nonejectable 
volume kind) to an ejectable volume kind. If the volume name or creation date 
of the hard drive changes after alias creation, the aliases may not resolve 
properly You can avoid this problem by ensuring tliar the volume name of the 
hard disk doesn’t change while you’re building a CD-ROM’s content. Also, do 
not back up, reformat, or restore a hard disk while you’re building a CD-ROM’s 
content, so that the creation date doesn’t change. 

Sometimes, vaiid-looking aliases fail to resolve. Because the Finder creates alias 
files, the Finder is responsible for resolving them. The Finder doesn’t always 
check and update aliases as carefully as you might. Additionally, the Finder 
always uses a relative search patli when resolving aliases. 

You might want to test to see whether installing QuickTime makes a difference 
in the cases where perfectly valid looking aliases hi! to resolve. QuickTime 
includes patches that make the Alias Manager work better. 


Q 

A 


What does hokUng the Shift key down at stanup tuni oft'under System 7? 

This information isn’t documented; the following list isn’t guaranteed complete 
or accurate and is certain to change in the Future. Under System 7.1) through 
System 7.5 the following files are explicitly skipped: 


• A/ROSE 

• Virtual memory 

• Files of type sen' (Roman still works), ’edev’, RDEV, 'INTT’, cbnd', 
'fbnd', ’tbnd', 'adev', 'ddev', 'appe', 'fext\ 'AINF, and 'thng' 

• Finder Startup and Shutdown items (since the Finder Scripting Extension 
controls these tasks) 


MaesRug will not load under System 7,0, but it will load under System 7.5 if 
both the Option and Shift keys are held down. In addition, System 7.0 sets the 
disk cache to 64K, while System 7.5 sets it to 96K, 


Q 

A 


What does tm-ning evaything off in the Extension Manage?^ mraally mrn off? 

T'he only files the Extension Manager turns off are those that it shows. Mliich 
files will be turned off isn’t documented; the following list isn’t guaranteed 
complete or accurate and is certain to change in the future. 


Inhere are four creator types that the Extension Manager doesn’t show: ‘mntr’, 
"DMOV, 'extE', and 'SINF. Items of type 'extE' and 'SINE aren’t showm 
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because the Extension Manager extension has the creator of extE' and the 
Extension Manager control panel has the creator of 'BINE. This prevents you 
from using the Extension Manager to disable itself 

Also, the Extension Manager won't show any items of type *INTI '\ 'RDEV, or 
'cdev' if they have the “no INITs” E'inder flag set. 

The Extension Manager shows only items of type 'INIT', 'RDEV\ ’cdev', 
■PRES’s 'PRER\ 'adev', 'fext', scri', cbnd', 'fbdn\ 'tbnd', 'ddev\ appe', 'gc24\ 
'adrp\ ^dbgr^ 'dtil', ’APPLV ’FFIL\ 'pext\ and Vbnd^ 


Q 

A 


Da I always need m adl FrJohD 'mlQg to print a doamimt? Why? 

Yes, you do. The reason for this is tliat many drivers (notably LaserWriter 8) 
don't initialize the job-specific settings until Prjoblnit is called. Without this 
call, they fall back on die default, w'hich is usually stored in the driver in the 
PREC d resource. 


The normal definition of the PREC (which maps to a TPrint structure) doesn't 
have as much space as LaserWriter 8 needs. Because of this, LaserWriter 8 
stores some settings in this PREC 0 resource and others in the LaserWriter 8 
Prcfe file. This separation of LaserWriter settings can wreak havoc on a job run 
without die PrJobDialog call. 

If you absolutely mtist avoid displaying the job dialog bcjx, there are two ways 
to w^ork around it. Note that these are not supported methods, and by using 
either of them you*11 make your application hostile to QuickDraw GX and to 
Copland. 

• Elave users invoke the Print dialog as part of their preferences setup, and 
save the resulting print record. Every time you print, merge that print 
record in with a call to PrJobMerge. This w^ay each document can have its 
own page setup, accommodating things like printing on A4 paper instead 
of LTS letter. 

• ^Display** the job dialog, but never let die user see it. You can accomplish 
this by calling Prjoblnit, moving the resulting dialog offscreen, patching 
ModalDialog, and calling PrDlgMain, Your patched version of ModalDialog 
can return I for the OK button immediately, and youVe got the added 
benefit of actually calling all the code and having a relatively normal print 
loop. 


Q 


/Vff writmg a pfin ter driver^ and Vve noticed that when ! print a window from the 
Findet^ with my driver the kofns don V show ap. Wlmt gives? 


MdiatyouVe uncovered is an “optiniizarion” in the Icon Utilities. When 
drawing an icon, the Icon Utilities use CopyMask rather than go through die 
standard bottlenecks. This is true unless yoii*re saving to a PICT or you set a 
cenain low-memory global (which isn*t well documented) indicating that 
Copy Bits should be used. 


The following two macros tell the Icon Utilities to use CopyBits instead of 
CopyMask: 


tdefine setPrinting{) (*((short *)0x948) =0;} 
Idefine clearPrinting{) {*{(short *)0x948) = -1;} 
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Call setPrinting- in your PrOpenPage function and ckarPrinting in your 
PrC^losePage fimction, and all should be well* 


Q 

A 


VVImh LaseiWiiter drive7's are ColorSync ^are? 

Currently, LaserWriter driver 83 is the only ColorSync-aware LaserWriter 
driver; versions earlier than 83 are not. 


Q 

A 


IVhat does the 73,2 Printing Update /, / update? Why do J need it? 

"Fhis extension fixes a prinTing problem that may occur on Power Macintosh 
7200, 7500, 8500, and 9500 computers using System 7,5.2. Without this fix, 
your computer may freeze if you attempt to print on a network-based printer 
that’s busy. 


I'he update contains a new version of the LaserWriter driver (8,3.2) and also a 
fix to serial DMA. The changes fix the ATP and PAP networking protocol 
layers. 


An updated version of the PAlHVrkStation.o library will be distributed on a 
future version of the Mac OS Software Developer’s Kit; developers who have 
licensed the fibrary will l>e notified when the new fibraiy^ is available. 


Q 


Do QuickDraw 3D mesh contours run in the smm or the opposite direction as the face? 
Par exawpky if the face rum clockwisey will the contour run counterclockwise? 


d’he exterior face needs to be defined in a counterclockwise direction, hut the 
contours defining holes can rim in either direction. The mesh code is able to 
identify holes in a face. 


Q 


Vm using QuickDraw 5/2 l.Q on a Pmr€^' Macintosh 710(1 If 1 tiy to launch my 
applkatioji when QuickDraw 5/2 is disabled with the Extemhn Manager, I g^t a 
message that the applkathn caukbPt he opmed became QuickDraw >D could not he 
found. Since the application has to run evetj if the usei^ doesn't have QuickDraw 3D, 
what should I do ? 


You’re '‘hard linking” to the QuickDraw 3D shared Hbmry You need to “weak 
link” to the library instead. With Metrowerks Code Warrior this is trivial: 
simply select the project window, click the small triangle to the right of the 
library in the window; and choose the Import Weak option from the pop-up 
menu. In your code, use the Gestalt selector for QuickDraw' 312 to determine 
w'hether the library exists. If it does, you should additionally check at least one 
symbol in die libraiy* against kUnresolvedCFragSyinbolAddress to he sure the 
library w'as linked successfully, as described in Inside Alacintosh: PouhtPC Syste?n 
Software on page t-25. It’s possible for Gestalt to indicate that the library is 
available even though the weak link failed — for example, if there isn’t enough 
memory available. 


Q 


Pve been trying to use QuickTime to step through a movie of PI(3Ts activated hy 
keyboard input (that h\ press a key and the next frame is displayed). My problem is that 
I can't consistently step one frame at a time. H^Tafs the easiest way to move to the next 
frame? 
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A 

Q 

A 

Q 


A 


Q 

A 


Q 

A 


Q 

A 


The easiest way is to use a mo\de controller to accomplish this. You can send 
mcActionStep to the controller to bump the movie to a new frame, A little more 
work, but perhaps more suitable for you if you don't want to use a controller, is 
to use CjetMovieNextlnterestingTime to find the next frame. 


Is there any way to ask QuickTime, at the operating system level, whether any movies 
are mfrently playing? 

No, there's no supported way to do this. 


IVeVe writing a screen saver that plays QuickTime ?mvies. Our IVaitNextEvent loop is 
very basic, IVe've noticed that other hack^-ound applicatiom don^t get any time, even if 
we use IVaitNextEvent and make sure that MovksTask doesn't spend too much fmie 
playing the movie. However, if we add code to track update events with BeginUpdate 
a7id EfidUpdate the problem goes away. Why? 

QuickTime and other parts of the operating system are sending update events 
to your application. If these events aren’t handled, theyVe resent, resulting in no 
time yield to other applications. By calling BeginUpdate and EndUpdate or 
otherwise taking care of the update event inside your event loop, you allow 
yielding to other applications. See Macintosh Technical Note “Pending Update 
Perils” (TB 37) for more information. 


Is the data f-ate stored so?newhere in a QukkJhne movie? Ifmt, how can I co?npute it? 

The data rate isn^t stored in the movie, because a Quick^l'inie movie isn’t 
required to have a constant data rate: it can change over the duration of the 
movie. Typically, in the case of video, one sample equals one frame; in the case 
of sound and other media, this one-to-one relationship doesn*t necessarily hold. 
Additionally, none of the video samples in a continuous stream are exactly the 
same size, even if in practical terms this is often assumed. 

There are several possible methods of measuring the rate of samples, hut the 
quickest and easiest is to do what Movie Player does: for each track, get the 
media size and di^ade by the media duration. This provides a rough estimate of 
the data rate that should be suitable for most purposes and works for all types of 
movies, video and otherwise. 


Ifs cfitkai in my CD project to he able to load snmll QuickTime loop movies entirely 
into IL4M, This is still not suppotted in QuickTimefar Windows 2,03, Will this 
functionality be available soon, or should I focus m developing a workaroimd? 

Support for loading a movie into and playing it from RAM will not be in 
QuickTime for Windows 2,1. It is, however, still on Apple’s to-do list. For now, 
you can improve performance by copying your small movie to a temporary file 
on the hard drive. From there you can force it into the disk cache or DOS 
buffers by opening and reading all of it yourself. 


How can I place blue-screen video over a QuickTltne VR panorama ? 

For starters, you need to know the exact view over which you want to place the 
video. Note that if you’re only warping in one dimension, it may be a bit tricky. 


MACINTOSH O & A 


115 




To get a very close match, take the following stepsr 

L Push each individual frame of the video sequence through the Stitcher 

(assuming that the motion fits within a single photograph) with wrap turned 
off, and the same vfov set as for the panorama. The resulting images will be 
warped into the same space as your complete panc)rama. 

2, Either turn your single-frame image into a partial panoramic movie or 
replace the appropriate part in your background panorama with the single 
frame. 

3- Run the image through the p2mv and msnm tools, and use QuickTime VR 
to dew^arp it with warpMode 1 with the precise hpan^ vpan, and zoom data 
set. Yon may want to use p2mv with the “raw’* compressor to maximize your 
image quality. 

4. Capture the image from the screen. 

5. If you do this for every image (it can be automated widi scripting), you 
should get a completely matched mc3tit}n sequence that you can turn into a 
QuickTime mctvie with standard tools. This is where you should do your 
compression (not at step 3). 

This should mostly take machine time, not yotu- time. Steps 1 and 3 can be 

scripted in MPW. Step 2 can he scripted in AppleScript using Photo Flash or in 

DeBabelizer, and step 4 in HyperCard or Director. Step 5 uses ConvertToMovie. 

Once you develop these scripting tools the first time, each sequence should be 

pretty quick to fire up. 


Q 


My car exhibits a behavior / hope you cm expiam Evefj now ami again ^ he'll mijf 
something with particular attention and in tensity — the bend oftrty wrh% say, or a 
spot on the rug. So far so good. But thef? when he lifts his head, he holds his mouth open, 
his lowerfm' hanging stt^pidly. It looks ndiculous! And he seems totally unaware of ft 
invariably sitting therefor several secondsmouth gaping, looking ai'oimd blithely as if 
there ^s nothing out of the ordinary, before ftnaily licking his chops and closing his mmith. 
Whafs going on? Is there any way I can curb this behavior? It 's cfubafTassing. 


A 


First off, don’t worry. Your cat is perfectly normal. All cats do this, and there’s 
nothing wrong with it (except of course that it looks silly). Your cat is simply 
making use of a litde-known sensoiy organ called the vorneronasai organ, Or 
Jacobson’s organ. It’s a second scent organ, located far forward on the roof of 
the mouth, and is supplemental to — but distinct from — the nose. lEs even 
wired into slightly different areas of die brain, areas dealing with feeding and 
complex sexual behaviors. Many other animal species have a Jacobson’s organ, 
from rattlesnakes to bighorn sheep, but humans don’t 


The behavior youVe noted is called flehmen reaction (flehmen is a German 
word with no satisfactory English translation). By holding his mouth open and 
not breathing, your cat is concentrating the molecules to be sensed over his 
Jacobson’s organ, allowing it to do its job. The behavior is exhibited by all cats, 
domestic and wild, large and small. 


These answers are supplied by the technical 
gurus (fi Applets Developer Support Center. For 
more answers, see the Macintosh Technical Q&As 
on this issuers CD or on the World Wide Web at 


http: //d e V. i n fo .o pple. com/tech qa/Main, htm t. 
jOlder Q&As can be found in the Macintosh 
Q&A Techntcol Notes on the CDJ* 
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KON & BAL'S PUZZLE PAGE 


Printing, Patching, and Fonts 


See if you can solve this programming puzzle, presented in the form of 
a dialog between guest puzzlers Dave Mersey and Cameron Esfahani 
(cam). The dialog gives clues to help you. Keep guessing until yoiTre 
done; your score is the number to the left of the clue that gave you the 
correct answer. Even if you never iim into the particular problems 
being solved here, you HI learn, some valuable debugging techniques that 
will help you solve your own programming conundmtm. 



DAVE HERSEY AND 
CAMERON ESFAHANI 


Dave 

cam 


Dave 

earn 

Dave 


cam 

Dave 

cam 

Dave 

cam 

100 Dave 
cam 
Dave 


Hey cam, it^s kinda quiet. Where are KON and BAL? 

Since the local salad bar closed, I haven’t seen KON* BAL tlisappeared 
after he left the vitleo game industry. Have you been getting enough 
sleep? You look tired, 

Pve been under a lot of pressure to track down this bug. 

Maybe I can help, WTiat’s the problem? 

I have a Power Mac 6100/66 running System 7,5 with QuickDraw GX 
1.1. When I try to print from a word processor, 1 get the me,ssage 
■The application has unexpectedly quit, because an error of type 11 
occurred.” Udiat’s an error of type 11 ? 

That’s an unhandled exception from native code. What word processor 
are you using? 

Um, a very large one in a very large office suite from a very large 
company up north. 

Have you updated to version 1.1.3 of QuickDraw GX? 

Yeah. The problem still happens. 

Does it happen on any other machine? 

Yes* It crashes on any Power Mac but works fine on 680x0 machines. 
Hmm, Is the word processor native on the Power Mac? 

Yes — it’s fat. 


DAVE HERSEY (AppleLink HERSEY) works in the 
QuickDraw GX PrintShop level 4 bio-containmeni 
facility, thousands of feet beneath the Cupertino 
RStD campus. There, he develops PowerPC-native 
QuickDraw GX printing code, works on Copland, 
and relaxes by dabbling with an occasional hot 
agent over lunch.* 


CAMERON ESFAHANI (AppleLink DIRTY, 
Internet dirty@powertalk.Qpple.com) is the 
shortest member of the Graphics team at Apple. 
To add Q few more inches to his height, he 
sometimes wears roller blades in meetings. If that 
doesn't help, he has been known to don hEs large 
purple hat with sparkles. * 
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cam 

90 Dave 

cam 

Dave 

cam 

SO Dave 


cam 

Dave 

cam 

Dave 

cam 

70 Dave 


cam 

Dave 

cam 

60 Dave 

cam 

Dave 

cam 

Dave 

cam 

Dave 

cam 

SO AJex 


Dave 


It sure is. But I have the same version of system software and the same 
word processor, yet my machine doesn’t crash. 

Well, I have a standard system installed, but I added a bunch of whizzy 
fonts. 

If (install one of your fonts, will my machine crash? 

Sometimes. If you install all my fonts, it crashes all the time. 

That’s easy, then: bad fonts. Here, take out this Thingamajigs font. 

No way man. This is a standard bitmap-only font It should work. 

Ike’s machine doesn’t have Thingamajigs on it and his machine still 
crashes. 

Does he have bitmap-only fonts installed? 

Yes, 

At what point in the printing process do you crash? 

The crash occurs just as the application starts spooling the print file. 

Is this word processor QuickDraw GX-aware? 

Yes. It has support for the new' QuickDraw GX print dialogs, and it 
calls the Quickl^raw GX translator to translate QuickDraw drawing 
commands into QuickDraw^ GX shapes during printing. 

Good for them. Have you tried to reproduce the crash w'ith otlier 
QuickDraw CiX-awai c applications? 

Yup. 1 tried to reproduce it w'ith several QuickDraw GX-aware and 
QuickDraw^ GX-savvy applications. No luck. 

Try running the 680x0 version of this program on your Power Mac. It 
will he slow and piggy, hut try it an^Tvay 

The problem w'cnt away! So, the crash seems to have something to do 
with the PowerPC code in this application. 

11mm, Let’s install MacsBug and take a look at this From the debugger, 

I tried that before, hut I couldn’t see any symbols in the PowerPC 
code where it crashes. I couldn’t tel) which routine the PC was in. 

You should install the new version of MacsBug, Version 6,5,2 
understands native exceptions and can use embedded symbols. 

Nifty.,., OK, I’ve done that. But I still crash. 

Why do you crash? Type how^, 

MacsBug claims that there was a '^PowerPC access exception at 
001DB030 Consti-uctNFNTDirectQry+Q02B4,” 

\Yliat does ConstructNFNTDirectory do? Hey wait, tliere’s AJex 
Beaman. AJex, can you help us out here? 

Sure, QuickDraw GX views all fonts as type 'sfnt'. It’s really elegant: 
ConstructNFNTDirectory will make an NFNT font appear to have 
an ‘sfht' directory. It can build either just the directory header or the 
entire director}^, and this is controlled by a Boolean parameter passed 
into the function. OK, gotta runl 

Thanks, Alex, Wlien I disassemble ConstructNFNTDirectory with 
MacsBug, I get this: 
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ilp ConstructHFNTDirectory 

Disassembling PowerPC code from ConstructNFMTDirectory 
Construe tl^FNTDirectory 


+00000 

001DAD7C 

stmw 

rl4,-0x004e{SP) 

+00004 

001DAD80 

mf Ir 

rO 

+00008 

001DAD84 

clrlwi 

r27,r5,0xl8 

+OOOOC 

001DADS3 

addi 

r28,r3|0x0000 

+00010 

001DAD8C 

Ttifcr 

rl2 

+00060 

OOIDADDC 

addi 

r3,r30,0x0000 

+00064 

OOIDADEO 

addi 

r4,r28|0x0000 

+00068 

001DADE4 

bl 

GetNoLoadResource 

+000E4 

001DAE60 

addi 

r3,r20,0x0000 

+OOOE8 

001DAE64 

bl 

Compti teSearchFields 

+OOOEC 

ooiDAEee 

cntiove 

cr7_SO,cr7_SO 

+OOOFO 

001DAE6C 

cmpwi 

cr2,r27,0x0000 

+002B4 

001DB030 

*lW2X 

r5,rl9,r5 

+002FO 

001DB06C 

Ihz 

r5,0x0004(r20) 

+002F4 

001DB070 

li 

rl6,0x0001 

+002F8 

001DB074 

addic 

r5,r5,0x0001 

+002FC 

001DB078 

sth 

r5,0xa004(r20) 

+00300 

001DB07C 

beq 

cr2,ConstructNFNTDirectory+0 0 3 2 4 

+oo 3 ca 

001DB144 

addic 

SP,SP,OxOOAO 

+003CC 

OOIDBHS 

mterf 

0x38,rl2 

+003DO 

0O1DB14C 

mtlr 

rO 

+003D4 

001DB150 

Imw 

rl6,-Ox0040(SP) 

+OO3D0 

00103154 

blr 



cam 


An access exception means we’re trying to read or write to an invalid 
address. That, of course, could be ca used by many things, such as 
uninitialized variables or trashed memory. Let’s check the heaps with 


he. 


Dave Both the system heap and the application heap are fine. 


cam OK, I restart the program and use bqj in MacsBug to set a breakpoint 
at ConstructNFNTDirectory, brp is just like br, except it works for 
PowerPC code. After 1 start printing and the breakpoint is hit, I step 
through this fimetion to follow the code flow, 

45 Dave At offset 0x0300 you don’t take that branch, and you eventually begin 
executing code that will corrupt die QuickDraw GX heap. 

cam But that’s wrong — we should’ve taken that branch. The caller didn’t ask 
ConstructNFNTDirectoty to create the entire directory, just its header; 
it didn’t allocate enough space for all of it, Clieck the heaps again, 

Dave The heaps seem fine. QuickDraw GX allocates out of its own heap, 
which MacsBug doesn’t know about. Even if it did know about it, it 
wouldn’t be able to tell us if the heap was corrupt, as QuickDraw GX 
has its own memory manager. 


cam Dam, memory cormption bugs axe the worst. You can trash memory 
and not see die effects of it until you’re miles away from that code, 
OK, why didn’t it take die branch at effect 0x0300? 
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30 Dave 
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25 Dave 
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Wellj CR2 is true, so the branch won’t be taken. 

How can you tell that CR2 is true? 

The PowerPC chip has eight condition register fields, CRO through 
CR7, stored in nibbles in a 32-bit condition register (Dave Evans 
talked about this in his column in d^velup Issue 21). So the value of 
CR2 would be bits 8 through 11 of the condition register. The chip 
has its bits numbered from 0 through 31, from left to right. We can 
tell that CR2 contains a true value because its second logical bit isn’t 
set. That bit corresponds to the equals operator, so the fact that it’s 0 
means the operation that set this register was not equal 

Who sets up CR2? 

The code at offset OxQOFO, As Alex mentioned, one of the parameters 
to this ftmction is a Boolean that controls whether the whole directory 
is created or only the header. Because this parameter is a Boolean, the 
PowerPC processor can just compare it against 0 and use the result as 
a flag for later branches. Parameters passed in PowerPC code are put 
from left to right into registers R3 through RIO; since diis parameter 
is the third parameter to the fiinction, it’s passed to the routine in 
register R5. {A much better description of this is in Inside iMacmtosh: 
Powcn^PC System Sojhmre.) 

1 love this chip. Ill reexecute the program and get back to the start of 
this ftmction and examine CR2. 

It Starts out false. 

So someone’s trashing it along the way. Well, we can’t use some of our 
normal tricks for detecting when memory gets trashed. One problem 
is tliat step spy doesn’t work yet for PowerPC. Another problem is thai 
we would want to step spy on C]R2, which is a register, and step spy 
never worked on registers. We’ll have to do this the hard way: let’s 
step through this function, watching (^R2 to see just when it gets 
changed. 

The subroutine GecNoLoadResource at offset 0x0068 changes CR2 
from false to true. GeiNoLoadResource is a wrapper to GetResource. 

I restart the program and trace over the GetResourec call. 

Yep, that’s the function that trashes CR2. 

Is it legal for the compiler to rely on CR2 being preserved across 
function calls? 

Yes. According to the PowerPC ABI (Application Binary Interface) 
documentation — section 3,6 in the first edition — CR2 through CR5 
are nonvolatile and need to be saved across function calls. 

Look at the code for GetResource. Since in System 7.5 GetResource is 
a native trap with a routine descri| 7 tor, I can use the MacsBug dcmd 
drd to dump that out. Here’s what I get: 

drd GetResource 

The RoutineDescriptor at: OllEDFEC 

Mixed Mode Magic Trap: J\AFE, version: 07, 
routine descriptor flags: 00 (Hotlndexable), 
loadLocation: OOOOOODO, reserved2: 00, 
selectorlnfo: 00 (No Selector), 
routine count: 0000 
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—- Routine Record 00000000 —— 

procinfo: 0OOOO2FO, reservedl: 00, ISAType: 01 (kPowerPCISA), 
Routine Flags: 0004 (IsAbsolute, IsPrepared, NativelSA, 

Pass Selector , IstlotDefault), procPtr: 01219EEC, 
storedOffset: OOOOOOOO, selector: 00000000 

20 Dave There’s rmly one routine associated with the trap and it’s the native 
implementation. 

cam WTiere’s that function? On the Power Mac, every ProcPtr is actually a 
data structure that contains the routine’s real address and TOC. This 
is called a TVector (transition vector). This allows every fragment to 
have its own globals, because the correct TOC gets loaded for each 
routine by the runtime environment. So, to find the routine’s address, 
you need to dereference the ProcPtr. 

wh 1219eec* 

Address 00E77B7S is in the ^'Porky WordProcessor'^ heap at 0ODFC43O 
The address is in a CFM fraguient "Porky WordProcessor" [non-write exec] 
It is 00073058 bytes into this heap block: 

Start Length Tag Mstr Ptr Lock Prg Type ID File Maine 

* 00E04B20 003D35D8+0C M 


T5 Dave Apparently it’s in the heap of the application. 


cam 


So this program is patching GetResource. At least they have a native 
patch — a good habit these days because you don’t know what traps 
will go native from now on. If you’re patching native PowerPC code 
with 680x0 code, performance-sensitive code will run slower. For this 
reason, you should make all of your patches fat. Let’s disassemble the 
patch on GetResource. 


ilp 1219eec'" 

Disassembling PowerPC code from 1219eec'' 


No procedure 
OOE77B78 

name 

stwu 

SP,-0x0058(SP) 

OOE77B7C 

mflr 

rl2 

0OE77B8O 

stw 

rl2,Ox0060(SP) 

00E77B34 

stmw 

r26,Ox0040(SP) 

OOETTBSB 

stw 

r3,Ox0070(SP) 

00E77BSC 

sth 

r4,Ox0074(SP) 

OOE77B90 

extsh 

r4, r4 

OOE77B94 

lis 

r5,0x4D42 

00E77B98 

ori 

r5,r5,0x4446 

OOE77B9C 

cmplw 

cr2,r3,r5 

OOE77C10 

Imw 

r26,Ox0040(SP) 

OOE77C14 

Iwz 

rl2,Ox0060{SP) 

OOE77C18 

mtlr 

rl2 

OOE77C1C 

addic 

SP,SP,0x0058 

O0E77C2O 

blr 



10 Dave At OxOOE77B9C they do a compare and store the result in CR2. 

However, they don’t save and restore CR2 across this functton, so it’s 
trashed when we return to ConstructNFNTDirectory. 

cam OK, I restart the program and manually save and restore the value of 
CR2 across the GetResource calls. T do this by fiitzing with bit 2 in CR2. 
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Dave Every'thing prints fine, 

cam It looks like a compiler biig. Either they shouldn’t be using CR2 or 
they should he preserving it In any case, the GetResource patch is 
trashing CR2, and that changes a Boolean which causes us to read in 
extra data. The caller never allocated enough space for the extra data, 
so the QuickDraw GX heap gets corrupted- 

Dave Holy cow! A compiler bug. Shouldn’t we notify the compiler 
developer? 

cam Well, this company has their own in-house development tools group. 
They write their own compilers, linkers, and debuggers. We should 
contact them anyway, so that they can create a patch that fixes this 
problem, jThh' patch, "'Off}ce4.2x Upd/ne for Power Mac, ^ is mw available 
m most milwe scf%icesj 

Dave Why are they patching GetResource? 

cam It looks like they were looking for resources of type 'MBDF' (menu 
bar definition procedures), 1 can tell this from the instructions at 
addresses 0x00E77B94 through OxOOE77B9C, The PowerPC 
architecture has a limitation of 16 bits on the size of an immediate 
constant. So, if you wanted to compare a value against a 32-bit 
constant, you would have to build the 32-bit value with two 
instructions. This is what occurs at addresses 0x00E77B94 and 
0x()()E77B98, where they insert 0x4D42 and 0x4446 together into a 
32-hit value. If you look at the ASCUl of this constant, it’s 'MBDF'. At 
address ()x00E77B9C, they compare this constant to the resource type 
parameter passed to GetResfuirce. Since that parameter is the first 
parameter, it will be in register R3. 

Dave WTiy didn’t w^e crash w hen we had only one NFNT font installed? 

cam This patch would cause C^anstructXFNTDirectory to always 

overwrite the buffer passed in. But that wouldn’t alw^ays cause your 
machine to freak out. By adding enough NFNT fonts, w^e trashed the 
QuickDraw GX heap significantly enough to cause the crash, 

Dave Wow', all this and it was an apphcatictn patch that caused the problem! 
It sure would have been cool if w^e could have used the patch demd, 

cam Yeah, The patch demd does wTjrks on the Power Mac — but we didn’t 
know' that was the prolilem when we started, 

Dave It’s interesting that it w'as an application bug. That w^ould explain why I 
crash in a spreadsheet application by the same company. They share 
the same patch, 

cam Nasty. 

Dave Yeah. 


SCORING 

80-100 You could have o promising career writing compilers for a company up north. 

45-70 Dr. MocsBug could always use another assistant. 

25-40 Don't worry, it took us a while to figure it out too. 

5-20 Visual Basic fan, are you?* 

Thanks Beamon, Tom Dowdy, Ron Voss, KON (Konstantin Othmer), and BAL (Bruce Leak) for 

reviewing this column.* 
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DirEnumerateGet (Macintosh 
Q&A) in 

DirFindRecordGet (Macintosh 
Q&A) in 

DirGetDirector^dnfo (Macintosh 
Q&A) in 

discontinuity, NURB airves and 
52 

display ID (Display Manager) 45 
Display Manager 44-^47 

determining version 44 
identifying displays 45 
walking the QuickDraw GX 
device list 39 

Display Manager 1.0 44, 45 
Display Manager 2,0 44 
DisplayManagerAware flag, 
Display Manager and 45 
Display Manager Development 
Kit 47 

Display Notice events, Display 
Manager and 45, 46 
D i s pose Vic wP urt V\T3 uffer 
(QuickDraw GX) 36, 37 
DALA (direct memory access), 
SCSI data transfers (Macintosh 
Q&A) 109 

DAICheckDisplayMode (Display 
Manager) 44-45 
D'MGetDisplayl DByGDevice 
(Display Manager) 45 
D MGetFi rstScreen I )evice 
(Display Manager) 44 
DMGetGDevice By L>i splaylD 
(Display Manager) 45, 47 
DMGetNextScreen Device 
(Display Manager) 44 
DMRegisterNotify Proc (Display 
Manager) 45 

DMSaveScreenPrefs (Display 
Manager) 45 

DMSetDisplayAlode (Display 
iVlanager) 44, 45 
document record structure (of a 
scene) (QuickTime \^) 8, 9 

double buffeting (QuickDraw GX) 
29,31 

versus drawing speed 31 -32 
Draw'ShapeBuffered (QuickDraw 
GX) 33, 37-42 
ducks 50 

See also NURB curves 


E 

EndUpdate (QuickTime) 
(Macintosh Q&A) 115 
eraser field 

(viewPortBuflferRecord) 34 
Esfahani, Cameron 1 17 
exception handling (C++), See C++ 
exception handling 
Extension Manager, turning off 
files (xMacintosh Q & A) 
112-113 

F 

fairioMain 

(DMGetDispiayl DByGDevice) 
45 

failToMain 

(DMGetGDeviceByDisplaylD) 

45 

Falco, Pete 5 

FDecompressImage (Macintosh 
Q&A) 110 

first-derivative continuity, NURB 
cur\^es and 52 

“Flicker-Free Drawing With 
QuickDraw GX” (Ayala) 29-43 
Flicker Free sample application 
30-31 

font scalers (QuickDraw GX) 26 
Font'IbPict (QuickDraw' GX) 27 

G 

gDebugSignal global variable 
(C++) 84, 85 

gDebugThrow global variable 
{C++) 84 

GDHandle data type 

(QuickDraw), and QuickDraw^ 
GX view device 39 
“Generating QuickTime 

Movies From QuickDraw 3D” 
(Falco and xMcBridc) 5-25 
get (xApple Script) 75 
GetAlI Resources (Newton) 95 
GetDeviccList (QuickDraw) 39, 
44 

GetMovi e N extIn te res tingTime 
{Macintosh Q & A) 115 
GetNextDevice (QuickDraw) 39, 
44 

GetResource, KON & BAL 
puzzle 120-122 

Global FnExists (Newton Q&A) 
101 


GlobalVarExists (Newton Q & A) 
101 

“Graphical Tniffles” 

(Marinkovich), the Display 
Manager 44-47 
group field 

(viewPortBufferRecord) 34 
GXDisposeShape 41-42 
GXDraw'Shape 37, 42 
GXFlattenFont 26-27 
GXGetDeviceBitmap 41-42 
GXGetShapeDeviceBounds 39 
GXNewShape 36 
GXNew Window Vi ewPorr 33 
GXSetBitmap 41 
GXSetTransfonnMapping 41 
GXSetViewDeviceBitmap 41 
gxShape object 36 
gxTransfonn object 36 
gxViewDevice object 34 

H 

Hersey, Dave 117 
homogenous representation of 
control points (NURB curves) 
61,64 

horizontal pan (QuickTimeAT) 6 

I 

immediate mode rendering 
(QuickDraw 3D), of NURB 
curves 65 ^ 66 
IncludeFiles variable 
(CodeWarrior) 88 
interactive movies. See object 
movies; panoramic movies; 
Qurckl'ime VR 
invmap field 

(viewPortBufferRecord) 34 
isHighLevel EventAware flag. 
Display Manager and 45 

j 

job dialog, avoiding display of 
(Macintosh Q&A) 113 
Johnson, Bolb 103 

K 

kDepthNotAvailabieBit 

{DxMCheckDisplayMode) 45 
kDMDisplayNotF oundErr 

(DxMGetbisplaylDByGDevice) 

45 
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k D M DispI ayNotFoundErr 

(DMGe tGDeviceByD isplay ID) 
45 

keyDeviceRect constant, Display 
Manager and 47 
keyDisplaylD constant, Display 
Manager and 47 
keyDisplayNewConfig, Display 
Manager and 45 
key D i s pi ay 01 d Co nfi g, Display 
Manager and 45 
klnkChar (Newton Q & A) 100 
kinks (in NURB curves) 58-60 
kNoSwitchConfimiBit 

(DMCheckDisplayAlode) 44 
knots {of NURB curves) 49^ 
54-57, 58-60 
editing 67 
insertion of 68-72 
number of 68 
kn(it vector 

nonuniform 57 
NURB curves and 55, 58 
‘‘KON & BAUs Puzzle Page” 
(Mersey and Esfahani), 

Printing, Patching, and Fonts 
117-122 

kQ3SubdivisionMethodConstant 
(QuickDraw 3D) 66, 67 
kQJSubdivisionMethodScreenSpace 
(QuickDraw 3D) 66 
kQ3 Su bdivisionMethodWorldSpace 
(QuickDraw 3 D) 66 

L 

languages frame (Newton) 91-96 
changing strings at run time 
97-98 

loading from resources 
93-96 

loading from text files 
92-93 

LaserWriter 8J, CoiorSync aware 
(Macintosh Q & A) 114 
linear object movies (QuickTime 
VR), See object movies 
(QuickTime VR) 
listPicker (Newton Q & A) 102 
Load command (Newton) 91, 92 
'LOG#' resources (Newton) 

93-96 

'LOG#' template (Newton) 94 
LockMemoryContiguous 
(Macintosh Q & A) 109 
LocObj (Newton) 90, 94, 97, 98 


M 

McBride, Philip 5 
MacintoshQ&A 108-116 
Macintosh Technical Notes 4 
Macintosh Technical Q&As 4 
Macintosh Tool box, throwing 
exceptions for errors 83 
MacsBug, loading under System 7 
(Macintosh Q & A) 112 
MakeBinary (Newton) 99 
Make command (CodeWarrior) 
87 

MakePSFlandle (QuickDraw GX) 
27, 28 

MakeSingleNodeMovie 
(QuickTime VR) 22 
Alarinkovich, Mike 44 
marker field 

(viewPortBufferRecord) 34 
zVlaroney, Tim 87 
'MBDF resources, KON & BAL 
puzzle 122 

mcActionStep (Macintosh Q & A) 

115 

MemError (Macintosh Toolbox) 
85 

Metrowerks CodeWarrior 
built-in SOM compiler 
87-89 

include files 88-89 
using G++ 80 
using Tool Server from 
87-89 

“weak linking” to 

QuickDraw 3D 114 
Metrowerks PowerPlant, 

UDebugging and UException 
files 83-84 

ModalDialog (Macintosh Q & A) 
113 

model (QuickTime VR) 6, 13-15 
getting the dimensions of 

11-12 

reading from 3DMF files 
10-11 

See aho object movies 
mode OK 

(DMCheckDisplayMode) 44 
Monitors control panel 44 
“MPW Tips and Tricks” 

(Maroney), using Tool Server 
from CodeWarrior 87-89 
multinode scene (QuickTime VR) 
6 

multipane dialogs 3-4 


MyAddlmageToMovie 
(Quick!’ime VR) 15, 17 
MyConvert 3 DMFToObject 
(QuickTime VR) 12 
My Gonvert3 DMFToPano 
^QuickTime VR) 18, 19 
MyGenerateObjlmages 
(QuickTime VR) 13-15 
MyGeneratePanoFrames 
(QuickTime VR) 18, 20-21 
iMy G en e r a te Pan oM ov i eD irect 
(QuickTime VR) 18 
Aly Ge tBoun dingS ph e re 
(QuickTime VR) 1 L 1 2 
MylnitObjCamera (QuickTime 
VR) 13, 14 

MylnitPanoCamera (QuickTime 
VR) 18, 19 

MyNewCamera (QuickTime VR) 

8 , 10 

jMy New Document (QuickTime 
'W) 8, 9 

MyP r e p ar e De s tM o vi e 
(QuickTime VR) 15,16 
MyRotateCameraY (QuickTime 
VR) 18, 20 

MyRotateObjectX (QuickTime 
VR) 13, 14 

MyRotateObjectY (QuickTime 
VR) 13, 14 

N 

name mangling (C++) 80 
preventing 81 

Names (Newton Q & A), adding 
items to 99 

Navigable Movie Player 
application 17 
Newton 

adding an index (Newton 

Q&A) 100 
adding items to built-in 
applications (Newton 
Q & A) 99 

localized strings for 90-98 
multiple Newton devices 
(Newton Q&A) 1 00 
Newton 2*0 (Newton Q&A) 
99-101 

Newton Q & A: Ask the Llama 
99-102 

Newton Toolkit L5, localized 
strings and 90 
N e wVi e wPtutVVrB uflfe r 

(QuickDraw GX) 33-36, 41, 
42 


INDEX 1 25 




node (QuickTime VR) 6 
nonuniform rational B-splines. See 
NURB curves 

Notes (Newton Q & A), adding 
items to 99 
NURB curves 48-74 

basis functions of control 
points 54-58 

Bezier representation of 68 
conic arcs 62-64 
controlling subdivision of 
66^7 

control points 49, 52-54 
converting Bezier curves to 
72, 73 

converting to Bezier curves 
72-73 

data structures in 

QuickDraw 3D 64-65 
designing with 73-74 
editing 67-68 
evaluating 69-72 
kinks 58-60 
knot insertion 68-72 
knots 49, 54-57, 58 h 50 
Oslo algorithm 72 
parametric functions and 51 
in QuickDraw 3D 64-68 
rendering 65-68 
smoothness of 51-52, 59 
three-dimensional 49 
useful properties of 49 
'‘NURB Ounces: A Guide for the 
Uninitiated” (Schneider) 

48-74 

NURB surfaces 48, 74 

See also NURB curves 

o 

object (QuickTime VR) 6 
rotating 1 3, 1 4 
shooting an object 6-7, 
13-15 

object combination (Newton) 93 
object movies (QuickTime VR) 5, 
6, 8-17 

adding rendered images to 
15, 17 

constructing 15-17 
converting 3 DMF files to 
12 

generating 17 
generating images for 15 
rotating tiie model for object 
rendering 13, 14 


setting initial camera 
position 13, 14 
‘'Office4.2x Update for Power 
Mac” 122 
ofEtfomi field 

(viewPortBuflferRecord) 34 
on_xfonn field 

(viewPortBuflferRecord) 34 
Open Driver (Macin tosh Q & A) 

no-111 

Open Transport (Macintosh 
Q & A) 111 

IP protocol stack 111 
Oslo algorithm, for inserting knots 
into NURB curves 72 
Ol'InetGetlnterfacelnfo 
(Macintosh Q & A) 111 

p 

page field (vievTortBufferRecord) 
34 

panorama (QuickTime VR) 6 
placing blue-screen video 
over (Macintosh Q & A) 

115-116 

shooting a panorama 7-8 
panoramic movies (QuickTime 
VR) 5,6, 8-12, 18-22 

converting die linear movie 
to an interactive movie 
22 

convemng 3 DMF files to 
18, 19 

dicing the image into a linear 
movie 21-22 
generating 21-22 
generating images for 18, 
20-21 

rendering directly 22, 23 
rotating the camera for 
panoramic rendering I 8, 
20 

setting initial camera 
position 18, 19 
simulating cylindrical 
rendering 22, 23-25 
slit'based rendering 22, 
23-25 

stitching the images 18,21 
'PAPA' -8192 resource (Macintosh 
Q&A) 110 

parametric functions, NURB 
curves and 51 
parent field 

(viewPortBufferRecord) 34 


patch dcmd, KON & BAL puzzle 
122 

pickerDef (Newton Q&A) 102 
PICrr movies, stepping through 
(Macintosh Q&A) 114-115 
PlainTalk microphone (Macintosh 
Q&A) 108 
Polaschek, Dave 26 
PostScript, downloading fonts 
with QuickDraw GX 26-27 
PowerMacintosh 9500 
memory allocation 

(Macintosh Q&A) 108 
sound-tn port (Macintosh 
Q&A) 108 

“PP DebugAlerts.rsrc” (C++) 84 
PrClosePage (Macintosh Q&A) 
114 

PrDlgMain (Macintosh Q & A) 
113 

preferences (AppleScript) 76-77 
grouping 77 
preferences property 
(AppleScript) 76-77 
“Print Hints” (Polaschek), 
QuickDraw GX Breaks the 
Space Hack 26-28 
Printing Update IJ (System 7,5,2) 
(Macintosh Q&A) 114 
PrJobDialog (Macintosh Q&A) 

113 

Prjoblnit (Macintosh Q&A) 113 
PrlobAIerge (Macintosh Q & A) 

"l 13 

PrOpenPage (Macintosh Q & A) 

114 

properties (AppleScript) 75-76 
multiple “group” properties 
77 

properties property (AppleScript) 
76 

protoKeypad (Newton Q&A) 

102 

protoSoupOverview (Newton 
Q & A), changing font style 
101-102 

Q 

Q3NURBCurve_GetData 

(QuickDraw 3D), editing 
NURB curves 66 
Q&A Technical Notes 4 
QuickDraw 3D 

controlling subdivision of 
NURB curves 66-67 
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data structures for NURB 
curves 64-65 

editing NURB curves 67-68 
generating QuickTitne VR 
TTiovies from 5-25 
immediate mode rendering 
65, 66 

mesh contours (Macintosh 
O&A) IM 
NURB curves 64—68 
rendering NURB curves 
65 h58 

retained mode rendering 
65-66 

“vi^eak linking” to 

(Macintosh Q ik A) 114 
See ahv NURB curves; 

3DMF files 
QuickDraw GX 

double buffering 29,31-32 
downloading PostScript 
fonts 26-27 
exporting pictures as 
QuickDraw PTCTs 
(Macintosh Q & A) 
109-110- 

flicker-free drawing 29-43 
font scalers 26 
offscreen buffer 33-37 
screen buffering librar)^ 
32-42 

space hack 26 
two-byte fonts 26, 27 
QuickDraw PICT files, converting 
QuickDraw GX pictures to 
109-110 

QuickTime for Windows, 

loading/playing movies in RAM 
(Macintosh Q & A) 115 
QuickTime movies, data rate 
(Macintosh Q & A) 115 
QuickTime 5-25 

Authoring Tools Suite (ATS) 

6 / 12,21 

placing blue-screen video 
over a panorama 
(Macintosh Q & A) 

115-116 

versus 3D models 5 
QuickTime \T. movies 

creating a new doc'ument 8, 

9 

creating the camera 8-10 
See ako cibject movies; 
panoramic movies 


R 

Rappoport, Avi 78 
rational curves, NURB curves and 
60-62 

RedoChildren (Newton) 98 
rendering camera (Quick"! nne 
VR) 

creating 8-10 
for linear object movies 
13-15 

for panoramic movies 18-21 
ResError (Macintosh Toolbox) 85 
retained mode rendering 
(QuickDraw 3 D), of NURB 
curves 65-66 
rowBytes (PixMap) 3 

s 

scene (QuickTime VR) 6 

document record structure 
for 8, 9 

Schneider, Philip J. 48 
screen buffering (QuickDraw GX) 
29,31 

versus drawing speed 31 -32 
screenview field 

(viewPortBufferRecord) 34 
Script Include File (CodeWarrior) 
88 

SCSI direct memory access 
(DMA) (Macintosh Q & A) 

109 

SCSI drivers, native (Macintosh 
Q&A) 108 

SCSI Interface Module (SIM), 
native (Macintosh Q&A) 108 
second - d eri va ti ve contin u i ty, 
NURB curves and 52 
set (AppleScript) 75, 76 
SetLocalizationFranie (Newton) 
90, 91, 97 

SetStdCProcs (Macintosh Q&A) 

110 

settmgs property (AppleScript) 
76-77 

S e tVi e wPo r t WB u ffe rD i the r 
(QuickDraw^ GX) 42 
Sharp, xMaurice 90 
signal macros (xMeti'ow^erks 
PowerPlant) 85 
Simone, Cal 75 

sht-based rendering (QuickTime 
V^) 22,23-25 

calculating the optimal slit 
width 24, 25 


SOjVI (System Object Model) 
(IBM), CodeWarrior and 
87-89 

space hack (QuickDraw) 26 
splines 50 

Sec aim NURB curves 
SrePiecToMovie (QuickTime VR) 
21-22 

stat’ parameter (ToolServer), 
CodeWarrior and 89 
status property (AppleScript) 76 
StdPix bottleneck (Macintosh 

Q&A) no 

Stitch?68 script (QuickTime VR) 
18, 21 

stitching tool (QuickTime VR) 

18, 21 

storage field 

(viewPan BufferRecord) 34 
'STR ’ -8192 resource (Macintosh 

Q&A) no 

switchFlags 

(DMCheckDisplayMode) 44 
SyneView (New'ton) 98 
System 7, startup witli the Shift 
key down (Macintosh Q&A) 
112 

System 7,52, Printing Update LI 
(Macintosh Q&A) 114 

T 

Technotes 4 
TextSetup (Newton) 91 
3DMF files (QuickDraw) 

converting to linear object 
movies 12 

converting to panoramic 
movies 18, 19 
creating QuickTime VR 
numes from 8-22 
reading models from 10-11 
til rowing exceptions (C+-I-) 79-80 
for Macintosh dbolbox 
errors 83 

tlirow macros (xMetrowerks 
PowerPlant) 84-85 
throw statement (C++) 79, 80, 84 
ToolP'roniEnd file (CodeWarrior) 
87, 89 

ToolFroniEnd panel 
(CodeWarrior) 87-88 
ToolServ^er, using from 
CodeM^arrior 87“89 
top-level exception handler (C++) 
80-81 
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TQlNURBCurveData 
(QuickDraw 3D) 

converting Bezier curves to 
NURB curves 72 
editing NURB curves 67 
"IhieTvpe GX scaler (QuickDraw 
GX) 26 

try blocks (C++)j definittg 81 
try statement (C++) 79, 81 
two-byte fonts (QuickDraw GX) 
26, 27 

Type 1 scaler (QuickDraw GX) 
26 


UDebugging file (Metrowerks 
PowerPlant) 83-84 

global variable options 84 
signal 84 
signal macros 85 
UException file (Metrowerks 
PowerPlant) 83-84 
throw macros 84-85 
uniform knot vector, NURB 
curves and 55-56 


updatearea field 

(viewPortBufferRecord) 34 
Update ViewPDrtWBuffer 
(QuickDraw GX) 36-37 
usehaJftone field 

(viewPortBufferRecord) 34 
“Using C++ Exceptions in C” 
(Rappoport) 78-86 

V 

vertical pan (Quick'fime VR) 6 
“Veteran Neophyte, The^ 

(Johnson, Bo3B), Killing Time 
Killers 103-106 
viewBounds (Newton) 98 
viewdelta field 

(viewPortBufferRecord) 34 
view field (viewPortBufferRecord) 
34 

ViewPortBufferRecord data 

structure (QuickDraw^ GX) 33, 
34, 42 

viewSetupFormScript (Newton) 
91,98, 100-101 

virtual reality. Sec QuickTime VR 


w 

weight (of control points), NURB 
curves and 60 

weighted Euclidean representation 
of control points (NURB 
curves) 62 
window field 

(viewPortBufferRecord) 34 
Worksheet window 
(CodeWatrior) 87 


Want to ShoiB off yoiiP cool code? 



YOUR NAME HERE 


Do you have code that solves a problem other Macintosh 
developers might be having? Why not show it off by writing 
about it in dnk’iop? We Ye always looking for people who might lie 
interested in siihmitting an article or a column. If yoif d like to 
spotlight and distribute your code to diousands of developers of 
Apple products, here’s your opportunity. 

If youYe a lot better at writing code than writing articles, don’t 
worry. An editor will work with you. The result will be something 
you’ll be proud to show your colleagues (and your Mom). 

So don’t just sit on those great ideas; feel the thrill of seeing them 
published in developl 

For Author’s Guidelines, editorial schedule, and information 
on our incentive program, send a message to DEVELOP on 
AppleLink, develop@applelLnk.apple.coiTi on the Internet, nr 
Caroline Rose, Apple Computer, Inc,, 1 Infinite Loop, 

Cupertino, CA 95014. 
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RESOURCES 


Apple provides a wealth of mfmmation, 
prodmts^ aiid services to assist developers. 
The Apple Developer Catalog and Apple 
Developer University are open to anyone 
who watits access to development took 
and instniction. Additional information 
and services are availabk tbmugh 
Apple's Developer Pro^ams. 


Apple Developer Catalog To order 
product or receive a catalog, coli 1-800- 
282-2732 In the U.S., 1-80CT637-0029 in 
Conada, (716)871-6555 internationally, 
or (716)871-651 1 for fax. You con also 
send e-mail to AppleLink A PDA, Internet 
apda@opp[e[ir^k.app!e.cam, Americo Online 
APDAorder, or CompuServe 76666,2405. 
Or write Apple Developer Catalog, P.O. 

Box 319, Buffalo, NY 14207^)319. 


The Apple Developer Catalog 

This complimentary catalog offers 
worldwide access to development 
tools, resources, training products, 
and infomiation for anyone 
interested in developing applications 
on Apple platforms. It features 
hundreds of Apple and third-party 
development products and offers 
convenient payment and shipping 
options, including site licensing. 

Apple Developer University 

(DU) provides courses to get you 
started programming on Apple 
platforms and Mac OS-compadble 
hardware, as well as advanced, in- 
depth training on new technologies 
such as QuickTime VR, QuickDraw 
3D, OpenDoc, Apple Guide, and 
Newton. In addition to classroom 
training, multimedia self-paced 
courses and low-cost mini-course 
tutorials are available through the 
Apple Developer Catalog. 

Macintosh Developer Programs 

Macintosh developers have a choice 
of three programs, each providing 
technology seeding, development 
software, technical information, 
discounts on equipment, and more. 
The programs vary in the level of 
technical support provided. 

The Macintosh Associates Program is a 
low-cost self-support program for 
Macintosh developers who don^t 
need programming-level technical 
support from Apple. 


Apple Developer University (DU) 

Course descriptions and schedules can be 
found in the Developer Services areas on 
AppleLink (Developer Support] and the World 
Wide Web (http://devjnfo.appfe.com). You 
can also coll (408)9744897, fax (408)974- 
0544, send e-matl to AppleLink DEVUNIV, 
or write to DU at Apple Computer, Inc., 

1 Infinite Loop, M/S 305-1TU, Cupertino, 

CA 95014. 


The Macintosh Associates Plus Progra?n 
enables Macintosh developers to 
have up to ten programming-level 
technical support questions 
answered (via e-mail) per year, 

7'be Macintosh Partners Program is 
for developers who need unlimited 
prograniming-levei technical 
support (via e-mail). 

Newton Developer Programs 

Newton developers have a choice 
of three programs, each providing 
technical information as well as 
discounts on equipment and 
developer training. The programs 
vary in the level of technical support 
provided. 

The Newton Associates Progra?n is a 
low-cost self-support program for 
Newton developers who don't need 
programming-level technical 
support from Apple. 

The Newton Associates Plus Program 
enables Newton developers to have 
up to ten programming-level 
technical suppon questions 
answered (via e-mail) per year. 

The Newton Partners Program offers 
Newton developers unlimited 
programming-level technical 
support (via e-mail) along with 
additional hardware purchasing 
privileges and platform seeding 
opportunities. 


Apple Developer Progroms Call the 
Developer Supporl- Center at (408)9744897, 
send e-mail te AppleLink DEVSUPFORX or 
write Developer Support, Apple Computer, 
Inc,, 1 Infinite Loop, M/5 303-2X Cupertino, 
CA 9501 4, for information or on application 
form. Developers outside the U.S. and 
Conoda should instead contact the Apple 
office in their country for information about 
developer programs. 
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